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Preface 


Few  personal  computers — indeed  few  computers  of  any  kind — 
have  been  as  thoughtfully  designed  or  as  attractive  to  people 
who  enjoy  programming  as  the  Commodore  128.  It  has  sev- 
eral environments,  optimized  disk  access,  16  memory  config- 
urations, and  dozens  of  special  codes,  escape  sequences,  and 
screen  controls.  It's  a  generously  equipped  toolbox  for  people 
who  like  to  customize  their  computers  and  their  software.  And 
it  offers  the  programmer  a  set  of  tools  which  are  hitherto  un- 
matched in  variety  and  power  in  a  consumer  computer. 

It  represents  the  best  of  a  breed:  the  eight-bit  machine. 
These  computers  are  built  on  chips  which  work  with  one  byte 
at  a  time— the  8502  chip  in  the  128  and  the  6502  chip  upon 
which  most  of  the  first  consumer  computers  were  built.  They 
are  a  technology  in  its  twilight,  but  the  128  has  significant 
strengths  and  could  well  survive  for  years  as  a  model  of  what 
personal  computers  can  be. 

The  68000  chip  is  emerging — Commodore's  Amiga,  Atari's 
ST,  and  Apple's  Macintosh  all  use  it — and  no  one  can  turn 
back  the  clock.  This  new  68000  is  bigger,  faster,  and  much 
more  flexible  than  eight-bit  chips.  It  can  manipulate  four  bytes 
at  a  time  and  directly  access  massive  amounts  of  memory.  It 
doesn't  need  to  switch  banks,  and  it  races  along  at  eight  times 
the  speed  of  the  older  chips.  It's  the  end  of  an  age. 

Nevertheless,  excellence  can  and  often  does  appear  at  the 
end  of  an  age.  Bach,  probably  the  finest  musician  ever,  sum- 
marized and  synergized  the  music  of  his  time.  He  embodied 
the  best  of  what  was  then  known.  As  it  turned  out,  his  sum- 
maries and  synergism  have  proven  timeless  and  durable. 
There  has  been  more  dramatic  music  since,  equal  music  per- 

P")  haps,  but  no  better  music.  The  Commodore  128  is  a  complex, 

full,  and  rich  summation  of  the  best  that  is  possible  with  an 
eight-bit  machine  architecture.  It  is  a  classic  programmer's 

J"— j  computer.  You  can  spend  years  exploring  its  abilities. 

However,  the  heart  of  a  computer  is  only  accessible  via 
machine  language.  Several  years  ago  I  decided  to  learn  to  pro- 

("""(  gram  in  machine  language,  the  computer's  own  language.  I 

—  understood  BASIC  fairly  well  and  I  realized  that  it  was  simply 

not  possible  to  accomplish  all  that  I  wanted  to  do  with  my 
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computer  using  BASIC  alone.  BASIC  is  sometimes  just  too  slow. 

I  faced  the  daunting  (and  exhilarating)  prospect  of  learn- 
ing to  go  below  the  surface  of  my  computer,  of  finding  out 
how  to  talk  directly  to  a  computer  in  its  language,  not  the 
imitation  English  of  BASIC.  As  I  was  to  discover,  something 
amazing  lies  beneath  BASIC. 

Few  events  in  learning  to  use  a  personal  computer  have 
had  more  impact  on  me  than  the  moment  that  I  could  in- 
stantly fill  the  TV  screen  with  any  picture  I  wanted  because  of 
a  machine  language  program  I  had  written.  I  was  amazed  at 
its  speed,  but  more  than  that,  I  realized  that  anytime  large 
amounts  of  information  were  needed  onscreen  in  the  future — 
it  could  be  done  via  machine  language.  I  had,  in  effect,  created 
a  new  BASIC  "command"  which  could  be  added  to  any  of  my 
programs.  This  command — using  a  SYS  instruction  to  send  the 
computer  to  my  custom-designed  machine  language  routine — 
allowed  me  to  have  previously  impossible  control  over  the 
computer. 

BASIC  might  be  compared  to  a  reliable,  comfortable  car. 
It  will  get  you  where  you  want  to  go.  Machine  language  is  like 
a  sleek  racing  car — you  get  there  with  lots  of  time  to  spare. 
When  programming  involves  large  amounts  of  data,  music, 
graphics,  or  games,  speed  can  become  the  single  most  im- 
portant factor. 

After  becoming  accustomed  to  machine  language,  I  de- 
cided to  write  an  arcade  game  entirely  without  benefit  of 
BASIC.  It  was  to  be  in  machine  language  from  start  to  finish.  I 
predicted  that  it  would  take  about  20  to  30  hours.  It  was  a 
space  invaders  game  with  mother  ships,  rows  of  aliens,  sound 
...  the  works.  It  took  closer  to  80  hours,  but  I  am  probably 
more  proud  of  that  program  than  of  any  other  I've  written.  ,     i 

After  I'd  finished  it,  I  realized  that  the  next  games  would  — ' 

be  easier  and  could  be  programmed  more  quickly.  The  mod- 
ules handling  scoring,  sound,  screen  framing,  delay,  and  i     > 

player/enemy  shapes  were  all  written.  I  only  had  to  write  i / 

new  sound  effects,  change  details  about  the  scoring,  create 
new  shapes.  The  essential  routines  were,  for  the  most  part,  al- 
ready written  for  a  variety  of  new  arcade-type  games.  When 
creating  machine  language  programs,  you  build  up  a  collection 
of  reusable  subroutines.  For  example,  once  you  find  out  how  ,    i 

to  make  sounds  on  your  128,  you  change  the  details,  but  not  i 1 

the  underlying  procedures,  for  any  new  songs. 
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j™"?  The  great  majority  of  books  about  machine  language  as- 

sume a  considerable  familiarity  with  both  the  details  of 
microprocessor  chips  and  with  programming  technique.  This 
T~|  book  assumes  only  a  working  knowledge  of  BASIC.  It  was  de- 

1  signed  to  speak  directly  to  the  amateur  programmer,  the  part- 

time  computerist.  It  should  help  you  make  the  transition  from 
r"1  BASIC  to  machine  language  with  relative  ease. 

You'll  quickly  discover  that  machine  language  is  your  key 
to  the  excellence  and  power  waiting  within  Commodore's  128. 


n 
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If  you  prefer  to  purchase  a  disk  containing  the  complete 
source  and  object  code  for  the  assembler  and  most  of  the 
programs  in  this  book  rather  than  type  them  in,  just  use 
the  convenient  coupon  in  the  back  or  call  toll-free  i-8@0- 
346-6767  (in  New  York,  212-887-8525).  ^ 
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Why  Machine  Language? 


Sooner  or  later,  many  programmers  find  that  they  want  to 
learn  machine  language.  BASIC  is  a  fine  general-purpose  tool, 
but  it  has  its  limitations.  Machine  language  (often  called 
assembly  language)  performs  much  faster.  BASIC  is  fairly  easy 
to  learn,  but  most  beginners  do  not  realize  that  machine  lan- 
guage can  also  be  easy.  And,  just  as  learning  Italian  goes 
faster  if  you  already  know  Spanish,  if  a  programmer  already 
knows  BASIC,  much  of  this  knowledge  will  make  learning 
machine  language  easier.  There  are  many  similarities. 

This  book  is  designed  to  teach  machine  language  on  the 
Commodore  128  to  those  who  have  a  working  knowledge  of 
BASIC.  For  example,  Chapter  9  is  a  dictionary  of  BASIC  com- 
mands. Following  each  BASIC  command  is  a  machine  lan- 
guage routine  which  accomplishes  the  same  task.  In  this  way, 
if  you  know  what  you  want  to  do  in  BASIC,  you  can  find  out 
how  to  do  it  in  machine  language. 

To  make  it  easier  to  write  programs  in  machine  language 
(called  ML  from  here  on),  most  programmers  use  a  special 
program  called  an  assembler.  This  is  where  the  term  assembly 
language  comes  from.  ML  and  assembly  language  programs 
are  both  essentially  the  same  thing.  Using  an  assembler  to  cre- 
ate ML  programs  is  far  easier  than  being  forced  to  look  up  and 
then  POKE  each  byte  into  RAM  memory.  That's  the  way  it 
used  to  be  done,  when  there  was  too  little  memory  in  comput- 
ers to  hold  languages  (like  BASIC  or  assemblers)  at  the  same 
time  as  programs  created  by  those  languages.  The  old-style 
hand-programming  was  very  laborious. 

There  is  an  assembler  at  the  end  of  this  book  called 
LADS,  for  Label  Assembly  Development  System.  It  will  let 
you  type  in  ML  instructions  (like  INC  2)  and  will  translate 
them  into  the  right  numbers  and  POKE  them  for  you  wher- 
ever in  memory  you  decide  you  want  your  ML  program  to  be 
located.  LADS  will  help  you  in  a  variety  of  other  ways  as 
well.  It  was  designed  to  offer  you  a  fast,  convenient,  and  effec- 
tive ML  programming  environment,  a  way  of  writing  pro- 
grams which  is  both  natural  and  familiar. 

ML  instructions  are  like  BASIC  commands;  you  build  an 
ML  program  by  using  the  ML  instruction  set.  A  complete, 
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descriptive  table  of  all  the  8502  ML  instructions  can  be  found  >     , 

in  Appendix  A.  Whenever  you  see  a  three-letter  abbreviation  LJ 

(like  INC)  in  this  book  that  you  don't  recognize,  it's  an  ML 
instruction  and  you  can  look  it  up  in  Appendix  A,  where  ■     , 

you'll  find  its  purposes,  modes,  and  syntax  fully  described.  LJ 

It's  a  little  premature,  but  if  you're  curious,  INC  2  will  in- 
crease the  number  in  your  computer's  second  memory  cell  . 
(the  second  byte  of  RAM  memory)  by  one.  If  15  is  the  number             LJ 
currently  in  cell  2,  it  will  become  a  16  after  INC  2.  Think  of  it 
as  "increment  address  two."  Like  BASIC,  ML  has  a  series  of 
commands  which  you  use  to  communicate  with  the  computer 
when  you  write  a  program.  ML  commands  are  always  three- 
letter  abbreviations,  like  INC,  and  LADS  will  help  you  write 
your  ML  programs  using  these  commands  and  numbers  that 
you  generally  add  to  the  commands  as  additional  information, 
like  INC  2. 

Throughout  the  book  you'll  be  learning  how  to  handle  a 
variety  of  ML  instructions,  and  LADS  will  be  of  great  help. 
You  might  want  to  familiarize  yourself  with  it.  Knowing  what 
it  does  (and  using  it  to  enter  the  examples  in  this  book),  you 
will  gradually  build  your  understanding  of  ML,  hexadecimal 
numbers,  and  the  extraordinary  range  of  new  possibilities 
open  to  the  computerist  who  knows  ML.  Knowing  ML,  being 
able  to  talk  directly  to  your  machine,  changes  things  so  much 
that  it's  like  getting  a  whole  new  computer,  a  much  more 
powerful  computer. 

Seeing  It  Work 

Chapters  2-8  each  examine  a  major  aspect  of  ML  where  it  dif- 
fers from  the  way  BASIC  works.  In  each  chapter,  examples 
and  exercises  lead  the  programmer  to  a  greater  understanding 

of  the  methods  of  ML  programming.  By  the  end  of  the  book,  \ j 

you  should  be  able  to  write,  in  ML,  most  of  the  programs  and 
subroutines  you  will  want  or  need.  , 

Let's  examine  some  advantages  of  ML,  starting  with  the  \ ) 

main  one — ML  runs  extremely  fast. 

Here  are  two  programs  which  accomplish  the  same  thing. 
The  first  is  in  ML,  and  the  second  is  in  BASIC.  They  get  re- 
sults at  very  different  speeds  indeed  as  you'll  see: 

Machine  Language 

169    1    160    0    153    0    4    153    0    5 

250  153  0  6  153  0  7  200  208  241  96 
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r— •  BASIC 

!     \  5  FOR  I  =  1  TO  1000:  PRINT  "A";:  NEXT  I 

These  two  programs  both  print  the  letter  A  on  the  screen 
p"|  1000  times.  The  ML  version  takes  up  21  bytes  of  RAM  (Ran- 

-  --  dom  Access  Memory).  The  BASIC  version  takes  up  45  bytes 

and  takes  about  30  times  as  long  to  finish  the  job.  If  you  want 
to  see  how  quickly  the  ML  works,  you  can  POKE  those  num- 
bers somewhere  into  RAM  and  run  the  ML  program  with  a 
SYS  command  to  the  little  program.  (For  this  and  other  ex- 
ample programs  in  this  book  which  directly  store  characters  to 
the  screen  RAM,  please  switch  to  40-column  mode  when  try- 
ing the  example.) 

In  both  BASIC  and  ML,  many  instructions  are  followed 
by  an  argument.  We  mentioned  the  instruction  INC  2.  In  that 
example,  the  number  2  is  the  argument.  In  BASIC,  the  SYS 
instruction  must  be  given  an  argument  which  tells  it  where  to 
SYS,  where  the  ML  program  it's  going  to  run  is  located  in 
RAM.  The  SYS  instruction  will  turn  control  of  the  computer 
over  to  the  address  given  as  its  argument.  There  would  be  an 
ML  program  waiting  there. 

Just  remember  that  an  argument  is  the  second  item  in  a 
pair  and  that  an  argument  modifies  (makes  more  specific)  a 
given  instruction.  In  the  pairs  INC  2,  SYS  2816,  and  Send  a 
Letter,  the  2,  2816,  and  Letter  are  the  arguments.  The  INC, 
SYS,  and  Send  are  the  instructions. 

To  make  it  easy  to  see  the  speed  of  our  1000  A's  example 
ML  program,  we'll  just  load  it  into  memory  without  yet  know- 
ing much  about  it.  We'll  use  a  BASIC  loader  program  that  sim- 
ply POKEs  all  the  numbers  of  the  ML  program  into  memory; 
then  you  SYS  2816  from  BASIC  to  activate  the  ML  program. 

This  little  ML  program  is  just  numbers  so  far  (and  that's 
all  the  computer  needs  anyway).  But  for  us  humans  it  would 
be  worthwhile  being  able  to  see  what  the  program  looks  like 
as  instructions.  There's  a  way.  A  disassembly  is  like  a  BASIC 
LIST.  You  can  give  the  starting  address  of  an  ML  program  to  a 
disassembler,  and  it  will  translate  the  numbers  it  finds  in  the 
computer's  memory  into  a  readable  series  of  ML  instructions. 
The  built-in  monitor  on  the  128  contains  a  disassembler  that 
you  can  use  to  examine  and  study  ML  programs.  Note  that 
you  have  to  give  a  start  address  whenever  you  write  (with  an 
assembler),  list  (with  a  disassembler),  or  run  (with  SYS)  an  ML 
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program.  That's  because,  unlike  BASIC  programs,  ML  pro-  v    . 

grams  can  be  located  anywhere  in  RAM  memory.  1_J 

Here's  what  our  little  example  ML  program  looks  like 

when  it  has  been  translated  by  a  disassembler:  ,     , 

0B00  A9  01     LDA  #$01  * — ' 

0B02  A0  00     LDY  #$00 

0B04  99  00  04  STA  $0400, Y  ,   , 

0B07  99  00  05  STA  $0500, Y  \ | 

0B0A  99  00  06  STA  $0600, Y 
0B0D  99  00  07  STA  $0700, Y 
0B10  C8        INY 
0B11  D0  Fl     BNE  $0B04 
0B13  60        RTS 

The  following  BASIC  program  (called  a  loader)  will  POKE 
the  ML  instructions  (and  their  arguments)  into  memory  for  you: 

10  FOR  I  =  2816  TO  2835:READ  A:POKE  I,A:NEXT  I 

20  PRINT"SYS  2816  TO  ACTIVATE" 

30  DATA  169,1,160,0,153,0,4,153,0,5 

40  DATA  153,0,6,153,0,7,200,208,241,96 

After  running  this  program,  switch  to  40-column  mode 
and  type  SYS  2816  as  instructed.  The  screen  will  instantly  fill. 

BASIC  stands  for  Beginner's  All-purpose  Symbolic 
Instruction  Code.  Because  it  is  all-purpose,  it  cannot  be  the 
perfect  code  for  any  specific  job.  The  fact  that  ML  speaks  di- 
rectly to  the  machine,  in  the  machine's  language,  makes  it  far 
the  more  efficient  language.  This  is  because  however  cleverly 
a  BASIC  program  is  written,  it  will  nevertheless  always  require 
extra  running  time  to  finish  a  job.  This  same  problem  slows 
down  every  other  computer  language  as  well:  Logo,  Forth, 
Pascal,  C,  whatever.  None  of  them  is  the  machine's  language 
and,  thus,  none  can  run  at  maximum  speed.  \    J 

To  see  why  this  is,  think  of  the  common  PRINT  instruc-  s-~* 

tion  in  BASIC.  A  PRINT  statement  drags  BASIC  into  a  series 
of  operations  which  ML  avoids.  BASIC  must  ask  and  answer  a  \  J 

series  of  questions.  Where  is  the  text  located  that  is  to  be 
printed?  Is  it  a  variable?  Where  is  the  variable  located?  What's 
its  length?  Where  on  the  screen  is  the  text  to  be  placed?  j    j 

ML  is  far  more  efficient.  As  we  will  discover,  ML  does  not 
need  to  hunt  for  a  string  variable.  And  40-column  screen  ad- 
dresses do  not  require  a  complicated  series  of  searches  in  an  j    I 
ML  program.  Each  of  these  tasks,  and  others,  slows  BASIC  " 
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<—■>  down  because  it  must  serve  so  many  general  purposes.  The 

I    I  screen  fills  slowly  because  BASIC  has  to  make  so  many  more 

decisions  about  every  action  it  attempts  than  does  ML. 

L.  j  Inserting  ML  for  Speed 

A  second  benefit  which  you  derive  from  learning  ML  is  that 
(— ^  your  understanding  of  computing  will  be  much  greater.  On 

(  }  the  abstract  level,  you  will  be  far  more  aware  of  just  how 

computers  work.  On  the  practical  level,  you  will  be  able  to 
choose  between  BASIC  or  ML,  whichever  is  best  for  the  pur- 
pose at  hand.  This  choice  between  two  languages  permits  far 
more  flexibility  and  allows  a  number  of  tasks  to  be  pro- 
grammed which  are  clumsy  or  even  impossible  in  BASIC. 
Quite  a  few  of  your  favorite  BASIC  programs  would  benefit 
from  a  small  ML  routine,  "inserted"  into  BASIC  with  a  SYS, 
to  replace  a  heavily  used,  but  slow,  loop  or  subroutine.  Large 
sorting  tasks,  smooth  animation,  and  many  arcade  games  and 
other  kinds  of  programs  must  involve  ML.  And  most  programs 
can  benefit  from  ML  patches.  It's  no  accident  that  nearly  all 
commercial  computer  programs  are  written  in  machine  language. 

BASIC  vs.  Machine  Language 

Because  of  the  great  efficiency  and  speed  of  ML,  it's  not 
surprising  that  BASIC  itself  is  written  in  ML.  It's  made  up  of 
many  ML  subprograms  stored  in  your  128's  Read  Only  Mem- 
ory (ROM).  BASIC  is  a  collection  of  special  words  such  as 
STOP  and  RUN,  each  of  which  stands  for  a  cluster  of  ML 
instructions.  One  such  cluster  sits  in  ROM  (unchanging  mem- 
ory) just  waiting  for  you  to  type  LIST.  If  you  do  type  in  that 
word,  the  computer  turns  control  over  to  the  ML  routine 
^  which  accomplishes  a  program  listing.  The  BASIC  programmer 

/    l  understands  and  uses  these  BASIC  words  to  build  a  program. 

You  hand  instructions  over  to  the  computer  and  then  rely  on 
—-.  the  convenience  of  referring  to  all  those  prepackaged  ML 

r    \  routines  by  their  BASIC  names.  The  computer  always  works 

with  ML  instructions.  That's  why  you  cannot  honestly  say  that 
you  truly  understand  computing  until  you  understand  the 
computer's  language:  machine  language. 

Another  reason  to  learn  ML  is  that  custom  programming 
is  then  possible.  Computers  come  with  a  disk  operating  sys- 
tem (DOS)  and  BASIC  (or  other  higher-level  languages).  After 
awhile,  you  will  likely  find  that  you  are  limited  by  the  rules  or 
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the  commands  available  in  these  languages.  You  will  want  to 

add  to  them,  to  customize  them.  An  understanding  of  ML  is  < [ 

necessary  if  you  want  to  add  new  words  to  BASIC,  to  modify 
a  word  processor  (which  was  written  in  ML),  to  personalize 
your  computer — to  make  it  behave  precisely  as  you  want  it  to. 
This  book  will  give  you  the  knowledge  and  the  tools  to  fully 
understand  and  to  speak  directly  to  your  128. 


BASIC'S  Strong  Points 

Of  course,  BASIC  has  its  advantages  and  in  some  cases  is  to 
be  preferred  over  ML.  BASIC  is  usually  simpler  to  debug  (to 
get  all  the  problems  ironed  out  so  that  it  works  as  it  should). 
In  Chapter  3  we'll  examine  some  ML  debugging  techniques 
which  work  quite  well,  but  BASIC  is  the  easier  of  the  two  lan- 
guages to  correct.  For  one  thing,  BASIC  often  just  comes  out 
and  tells  you  your  programming  mistakes  by  printing  error 
messages  on  the  screen.  Nevertheless,  if  you  use  the  LADS 
assembler  from  this  book,  it  too  will  print  error  messages  and 
identify  the  offending  line  number. 

Contrary  to  popular  opinion,  ML  is  not  always  a  memory- 
saving  process.  ML  can  use  up  about  as  much  memory  as 
BASIC  does  when  accomplishing  the  same  task.  Short  pro- 
grams can  be  somewhat  more  compact  in  ML,  but  longer  pro- 
grams generally  use  up  bytes  fast  in  both  languages.  However, 
worrying  about  using  up  computer  memory  is  quickly  becom- 
ing less  and  less  important. 

Soon  programmers  will  probably  have  more  memory 
space  available  than  they  will  ever  need.  The  128  is  particu- 
larly RAM  rich.  In  any  event,  a  talent  for  conserving  bytes, 
like  skill  at  trapping  wild  game,  will  likely  become  a  victim  of 
technology.  It  will  always  be  a  skill,  but  it  seems  as  if  it  will 
not  be  an  everyday  necessity. 

So,  which  language  is  best?  They  are  both  best — but  for 
different  purposes.  Many  programmers,  after  learning  ML,  find 
that  they  continue  to  construct  some  of  their  programs  in  BASIC 
or  some  other  language,  but  add  ML  modules  where  speed  is 
important.  An  all-ML  program  will,  however,  generally  be 
more  efficient,  more  flexible,  and  far  faster  than  any  alter- 
native. Remember,  it's  no  accident  that  the  great  majority  of 
professional  and  commercial  programs  are  written  in  pure  ML. 

But  perhaps  the  best  reason  of  all  for  learning  ML  is  that 
it  is  fascinating  and  fun. 
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How  to  Use  This  Book 


Throughout  this  book  there  are  short  example  programs  in 
machine  language  for  you  to  type  in  and  experiment  with. 
They  vary  in  length,  but  most  are  quite  brief  and  are  intended 
to  illustrate  an  ML  concept  or  technique.  The  best  way  to  learn 
something  new  is  often  to  just  jump  in  and  do  it.  Machine  lan- 
guage programming  is  no  different.  Machine  language  pro- 
grams are  written  using  a  program  called  an  assembler,  just  as 
BASIC  programs  are  written  using  a  program  inside  the  com- 
puter called  Microsoft  BASIC. 

This  book  includes  a  powerful  assembler,  LADS,  in 
Appendix  F.  In  addition  to  being  versatile,  LADS  offers  the 
beginner  a  number  of  conveniences  such  as  error  messages 
and  a  familiar  working  environment.  And  the  more  sophis- 
ticated features  of  the  assembler  are  there  for  you  when  you're 
ready  to  use  them. 

The  First  Step:  Assembling 

It  is  probably  a  good  idea  to  first  type  LADS  into  your  com- 
puter (typing  instructions  are  in  Appendix  F).  Once  you've  got 
a  working  version,  you're  ready  to  use  the  assembler  with  the 
practice  examples  throughout  the  book.  (If  you  prefer,  you  can 
order  a  disk  which  contains  LADS  and  other  programs  from 
this  book.  See  the  coupon  in  the  back  of  this  book  for  details.) 

Frequently,  the  examples  in  the  book  are  designed  to  do 
something  to  the  screen.  The  reason  for  this  is  that  you  can 
then  tell  at  once  if  things  are  working  as  planned.  If  you  are 

r""-,  trying  to  send  the  message  TEST  STRING  to  the  screen  and  it 

•'  -(  comes  out  TEST  STRI  or  TEST  STRING@,  you  can  go  back 

and  quickly  reassemble  with  LADS  until  you  get  it  right.  More 

T""t  important,  you'll  discover  what  you  did  wrong. 

'  -■  Many  programs  manipulate  data  within  a  database  or 

make  calculations  with  some  numbers  somewhere  in  RAM, 
but  the  action  takes  place  offscreen.  When  learning  ML,  how- 
ever, it's  often  helpful  to  put  your  data  manipulations  right  up 
in  front  of  your  eyes  on  the  screen  so  that  you  can  see  pre- 
cisely how  things  are  going.  When  everything  is  working  cor- 
rectly, you  can  redirect  the  data  to  some  less  visible  place 
elsewhere  in  RAM. 
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However,  the  80-column  screen  cannot  be  directly 
POKEd.  So,  while  LADS  works  with  40  or  80  columns,  you  [_J 

may  want  to  test  some  of  the  examples  using  the  40-column 
mode.  Any  examples  which  access  $0400  or  1024  (for  ex- 
ample, STA  $0400)  will  be  visible  only  on  the  40-column  ^  I 
screen.  You  can  assemble  the  source  code  in  80-column  mode, 
but  when  you  run  the  object  code,  it  will  not  be  visible  except 
in  the  40-column  mode.  Other  examples  use  JSR  $FFD2  or  JSR           [_j 
PRINT,  and  these  examples  will  run  as  is  on  either  screen. 

A  Sample  Program 

The  following  little  ML  program  will  show  you  how  to  go 
about  entering  and  testing  the  practice  examples  in  this  book. 
At  this  point,  of  course,  you  won't  yet  recognize  the  ML 
instructions  involved.  This  sample  program  is  intended  only  to 
serve  as  a  guide  to  working  with  the  examples  you  will  come 
upon  later  in  the  text. 

After  you've  typed  in  and  made  a  few  backup  copies  of 
LADS,  you  can  use  it  to  create  runnable  ML  programs.  De- 
tailed instructions  on  using  all  of  the  LADS  features  are  found 
in  Appendix  B,  but  for  now,  we  just  want  to  know  how  to  en- 
ter a  short,  easy  program. 

The  LADS  environment  is  very  like  BASIC.  In  fact,  you 
write  your  programs  as  if  you  were  writing  a  BASIC  program, 
except  you  use  ML  commands  rather  than  BASIC  commands. 
You  use  line  numbers  and,  if  you  wish,  colons  to  separate 
statements.  The  first  line,  however,  must  tell  LADS  where  you 
want  your  ML  program  located  in  memory  (since  ML  can  be 
placed  anywhere  in  RAM).  A  safe  place  to  locate  your  shorter 
ML  programs  is  address  2816  (we'll  learn  why  later),  so: 

10  *  =  2816 
20  .S 

30  .O 

31  LDA  #0:STA  $FFD0;  SWITCH  TO  BANK  15 
40  LDA  #65 
50  JSR  $FFD2 
60RTS 

Try  this.  Turn  on  your  computer.  If  you  have  a  1571  disk 
drive  with  a  bootable  LADS  disk  inside,  LADS  will  have  al- 
ready been  loaded  into  your  128  when  you  turned  it  on. 

If  you've  also  typed  in  the  LADS  loader  (see  Appendix  F), 
it  will  load  LADS  in  and  also  set  up  a  small  template  so  you 
won't  have  to  type  *=  or  .S  or  .O  each  time  you  start  a  pro- 

4 


U 


n 
n 

H 


Chapter  1 


gram.  If  you  prefer  not  to  have  this  template,  delete  the  POKE 
loop  in  line  50  of  the  loader. 
You  might  also  want  to  type 

j— j  AUTO10 

so  that  the  128  makes  automatic  line  numbers  as  you  type. 
Entering  an  ML  program  for  LADS  is  indistinguishable  from 
j?  entering  a  BASIC  program  as  far  as  the  128  is  concerned. 

So,  type  in  the  program  above,  in  BASIC  mode,  just  as  if 
it  were  a  BASIC  program.  If  you  didn't  have  LADS  autoload 
itself,  type  BLOAD"LADS".  Be  sure  to  use  BLOAD  so  LADS 
will  load  in  where  it's  supposed  to  be  in  RAM,  not  at  the  start 
of  BASIC  memory.  Then  type  SYS  10000  which  will  activate 
LADS,  and  you'll  see  your  program  changed  into  an  ML  pro- 
gram. This  transformation  is  called  an  assembly.  You've  just 
assembled  this  little  program. 

By  the  way,  the  LADS  loader  program  sets  up  the  Fl  key 
to  SYS  10000,  so  you  could  just  hit  Fl  instead  of  typing  SYS 
10000  if  you've  booted  the  LADS  disk.  You  can  hit  Fl  from 
anywhere  on  the  screen;  you  need  not  be  on  a  blank  line.  It 
will  clear  the  screen  as  does  LADS  when  it  begins  assembling. 

LADS  will  print  out  the  results  on  the  screen  while  it 
works  (the  .S  in  line  20  tells  LADS  to  provide  a  screen  listing 
to  show  you  what's  happening  during  assembly),  and  it  will 
store  the  resulting  finished  machine  language  program  in 
RAM  memory  starting  at  address  2816.  The  .O  in  line  30  tells 
LADS  to  store  the  program  into  RAM  memory. 

If  you  made  any  typing  errors  and  LADS  couldn't  as- 
semble this  program,  LADS  will  ring  the  bell  and  print  the 
line  number  where  the  error  is  located.  It  will  also  give  you  an 
error  message.  (To  fix  such  things,  just  LIST  and  change  the 
f**i  offending  line  as  you  would  to  modify  a  BASIC  program.)  You 

-  might  want  to  see  what  happens  if  you  change  line  40  to  a 

misspelling: 

f"l  40  LDR  #65 

Or  if  you  forget  to  give  the  number: 

40  LDR 

In  any  case,  once  you've  loaded  LADS  into  memory,  you 
won't  need  to  load  it  again  if  you  want  to  assemble  other  pro- 
grams later.  This  program  is  supposed  to  print  the  letter  A  on 
your  screen.  To  test  the  program,  simply  type  SYS  2816.  The 
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.O  caused  the  results  of  the  assembly  to  be  stored  in  RAM  ,     , 

where  you  can  test  them.  i_J 

The  little  ML  program  will  do  its  job,  you'll  see  the  letter 
A  appear,  and  then  the  computer  will  return  control  back  to  ,    , 

the  normal  BASIC  environment.  If  you  want  to  try  making  an  [ 1 

adjustment,  change  the  number  65  in  line  40  to  some  other 

number  to  print  a  different  character.  Type  LIST,  and  you'll  , 

see  that  your  original  program  is  still  there  in  memory  (2816  is  1 [ 

outside  the  ordinary  BASIC  programming  locations,  so  neither 
our  little  ML  program  nor  LADS  disturbed  our  code  written  in 
the  BASIC  environment).  Just  change  it  the  way  you  would 
change  a  BASIC  program  by  writing  over  the  1  and  pressing 
RETURN.  Then,  hit  the  Fl  key  or  type  SYS  10000  to  re- 
assemble the  new  version  and  test  it  again  with  SYS  2816. 

This  is  the  general  method  you'll  want  to  use  for  creating 
ML  programs.  There  is  another,  more  elaborate  way  to  handle 
very  large  ML  programs,  to  automatically  save  the  results  to 
disk,  and  a  number  of  other  LADS  features  we'll  come  to 
later.  For  now,  you  know  pretty  much  everything  you  need  to 
know  to  use  LADS  with  the  brief  examples  in  this  book.  (If 
you  want  to  experiment  with  all  LADS's  features  right  away, 
see  Appendix  B,  "How  to  Use  LADS.") 

The  main  thing  to  learn  here  is  how  to  type  in  programs 
and  assemble  them  using  LADS.  Primarily,  you  should 
remember  three  things: 

1.  LADS  always  has  to  know  where  you  want  to  store  your 
ML  program,  so  the  first  line  of  any  program  you  give 
LADS  must  have  *=  2816  and  nothing  else  on  that  line. 
We're  going  to  give  various  start  addresses  for  the  example 
programs  in  this  book  because  this  will  help  you  learn 
where  to  put  ML  and  learn  more  about  memory  usage.  But,  .    ( 

if  an  example  doesn't  have  *=  2816  as  the  first  line,  you  I — I 

can  safely  put  it  in.  Many  examples  are  given  in  the  form 
they  would  look  if  you  disassembled  them  from  the  mon-  |    t 

itor,  as  we'll  discover  in  Chapter  3.  However,  you're  always  s— j 

safe  putting  your  test  routines  at  2816. 

If  you  should  forget  to  include  a  starting  address, 
LADS  will  alert  you  to  the  fact  by  printing  an  error  message 
onscreen  and  halting.  Some  of  the  examples  give  *=  $B00 
as  the  starting  address,  but  that's  just  another  way  of  writ- 


n 

H 


n 


Chapter  1 


j— [■  ing  2816.  They  mean  the  same  thing,  but  $B00  is  hex  and 

L.'  we'll  learn  about  hex  in  the  next  chapter. 

2.  You  don't  need  to  tell  LADS  where  your  ML  program  ends. 
j*— j  Like  BASIC,  LADS  can  tell  when  it's  come  upon  the  last 

.'.  J  line  number  in  a  program.  You  can  just  type  in  a  program 

without  indicating  where  it  ends,  just  as  you  do  when  writ- 
r— >  ing  a  BASIC  program.  LADS  will  see  the  end  and  calculate 

' i  the  proper  addresses  in  RAM  to  store  your  entire  program. 

3.  You  should  be  in  BASIC  mode— you  should  see  READY— 
when  you  start  to  type  in  programs  that  you  want  LADS  to 
assemble.  The  environment  will  be  quite  familiar  if  you've 
done  any  BASIC  programming  (with  a  few  exceptions  such 
as  using  ;  instead  of  REM  as  illustrated  in  line  31  of  the  ex- 
ample above).  Generally,  though,  everything's  the  same  as 
BASIC.  You  can  use  AUTO  10  to  set  up  automatic  line 
numbering,  replace  lines  by  typing  their  number,  insert 
lines,  and  everything  else  you  would  do  when  working  with 
a  normal  BASIC  program.  Of  course  what  you  write  are  ML 
commands.  These  commands  are  not  the  same  commands 
as  BASIC'S,  but  that's  the  subject  of  rest  of  this  book. 
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The  Fundamentals 


The  difficulty  of  learning  ML  has  sometimes  been  exaggerated. 
There  are  some  new  rules  to  learn  and  some  new  habits  to  ac- 
/    \  quire.  But  most  ML  programmers  would  probably  agree  that 

ML  is  not  inherently  more  difficult  to  understand  than  BASIC. 
More  of  a  challenge  to  debug  in  some  cases,  but  it's  not 
worlds  beyond  BASIC  in  complexity.  In  fact,  in  the  1970s, 
many  of  the  first  home  computerists  learned  ML  before  they 
learned  BASIC.  This  is  because  an  average  version  of  the 
BASIC  language  used  in  microcomputers  takes  up  around 
12,000  bytes  of  memory,  and  the  early  personal  computers 
(KIM,  AIM,  etc.)  were  severely  restricted — they  had  only  a 
small  amount  of  available  memory.  These  early  machines 
were  unable  to  offer  BASIC;  it  took  up  more  space  than  they 
had,  so  everyone  programmed  in  ML. 

Interestingly,  some  of  these  pioneers  reportedly  found 
BASIC  to  be  just  as  difficult  to  grasp  as  ML.  In  both  cases,  the 
problem  seems  to  be  that  the  rules  of  a  new  language  simply 
are  "obscure"  until  you  know  them.  In  general,  though,  learn- 
ing either  language  probably  requires  roughly  the  same 
amount  of  effort. 

The  first  thing  to  learn  about  ML  is  that  it  reflects  the 
construction  of  computers.  ML  programmers  often  use  a  num- 
ber system  (hexadecimal,  or  hex  for  short)  which  is  not  based 
on  ten. 

We  count  by  tens  because  it  is  a  familiar  (though  ar- 
bitrary) grouping  for  us.  Humans  have  ten  fingers.  If  we  had 
\\  eleven  fingers,  the  odds  are  that  we  would  be  counting  by 

—  elevens. 


What's  a  Natural  Number? 

Computers  count  in  groups  of  twos.  It  is  a  fact  of  electronics 
that  the  easiest  way  to  store  and  manipulate  information  is  by 
]""}  on/off  states.  A  light  bulb  is  either  on  or  off.  This  is  a  two- 

group;  it's  binary,  and  so  the  powers  of  two  become  the  natu- 
^  ral  groupings  for  electronic  counters:  2,  4,  8,  16,  32,  64,  128, 

J~"l  256.  Finger  counters  (us)  have  been  using  tens  so  long  that  we 

have  come  to  think  of  ten  as  natural,  like  thunder  in  April. 
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Tens  isn't  natural  at  all.  What's  more,  twos  is  a  more  efficient  j     I 

way  to  count.  * — ■ 

To  see  how  the  powers  of  two  relate  to  computers,  we 

can  run  a  short  BASIC  program  which  will  give  us  some  of  )    i 

these  powers.  Powers  of  a  number  is  the  number  multiplied  by  ' — ' 
itself. 

Two  to  the  power  of  two  (2*2)  means  2  times  2  (in  other  s    | 

words,  4).  Two  to  the  power  of  three  (2*3)  means  2  times  2  * — ' 
times  2  (8). 

10  FOR  I  =  0  TO  16 
20  PRINT  2  A I 
30  NEXT  I 

ML  programming  can  be  done  entirely  in  the  familiar 
decimal  number  system.  For  beginners,  that's  probably  a  wise 
thing  to  do.  The  LADS  assembler  in  this  book  allows  you  to 
use  either  decimal  or  hex,  as  you  wish.  However,  you'll  prob- 
ably see  hex  used  in  magazine  articles  and  books,  and  hex 
does  format  on  the  screen  or  paper  more  neatly  than  decimal 
numbers.  Another  advantage  of  hex  is  that  it  relates  visually 
to  the  binary  numbers  that  the  computer  is  using.  The  argu- 
ments for  some  advanced  ML  commands  like  ROL  and  EOR 
are  more  easily  visualized  with  hex  than  with  decimal. 

Why  not  just  always  program  in  the  familiar  decimal 
numbers  (as  we  do  in  BASIC)?  Because  hex  is  based  on  groups 
of  16  digits,  not  decimal's  groups  of  10.  And  16  is  one  of  the 
powers  of  two.  Thus,  16  is  a  convenient  grouping  (or  base)  for 
ML  because  it  organizes  numbers  the  way  the  computer  looks 
at  numbers.  For  example,  at  the  most  elementary  level  all 
computers  work  with  bits.  A  bit  is  the  smallest  piece  of  infor- 
mation possible:  Something  is  either  on  or  off,  yes  or  no,  plus 
or  minus,  true  or  false.  This  two-state  condition  (binary)  can  j    j 

be  remembered  by  a  computer's  smallest  single  memory  cell. 
This  single  cell  is  called  a  bit.  The  computer  can  turn  each  bit 
on  or  off  as  if  it  were  a  light  bulb,  or  a  flag  raised  or  lowered.  J- 

It's  interesting  that  the  word  bit  is  frequently  explained  as 
a  shortening  of  the  phrase  Binary  digiT.  In  fact,  the  word  bit 
goes  back  several  centuries.  There  was  a  coin  which  was  soft 
enough  to  be  cut  with  a  knife  into  eight  pieces.  Hence,  pieces 
of  eight.  A  single  piece  of  this  coin  was  called  a  bit  and,  as 
with  computer  memories,  it  meant  that  you  couldn't  slice  it 
any  further.  We  still  use  the  word  bit  today  as  in  the  phrase 
two  bits,  meaning  25  cents. 
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|"""J  Whatever  it's  called,  the  bit  is  a  small,  essential  aspect  of 

computing.  Imagine  that  we  wanted  to  remember  the  result  of 
a  subtraction.  When  two  numbers  are  subtracted,  they  are  ac- 

f*~j  tually  being  compared  with  each  other.  The  result  of  the 

subtraction  tells  us  which  number  is  the  larger  or  if  they  are 
equal.  ML  has  an  instruction,  like  a  command  in  BASIC, 

f|  which  compares  two  numbers  by  subtraction.  It  is  called  CMP 

(for  compare).  This  instruction  sets  flags  in  the  CPU  (Central 
Processing  Unit)  of  the  computer,  and  one  of  the  flags  always 
shows  whether  or  not  the  result  of  the  most  recent  action 
taken  by  the  computer  was  a  zero.  We'll  go  into  this  again 
later.  What  we  need  to  realize  now  is  simply  that  each  flag — 
like  the  flag  on  a  mailbox — has  two  possible  conditions:  up  or 
down.  In  other  words,  this  information  (that  there's  a  zero  re- 
sult or  a  nonzero  result)  is  binary  and  can  be  stored  within  a 
single  bit.  Each  of  the  seven  flags  within  the  8502  chip  is  a  bit. 
Together,  the  flags  are  all  held  within  a  single  byte.  That  byte 
is  called  the  status  register. 

Byte  Assignments 

Our  computers  group  bits  into  units  of  eight,  called  bytes.  This 
relationship  between  bits  and  bytes  is  easy  to  remember  if  you 
think  of  a  bit  as  one  of  the  "pieces  of  eight."  Eight  is  a  power 
of  two  also  (two  to  the  third  power).  Eight  is  a  convenient 
number  of  bits  to  work  with  as  a  group  since  we  can  count 
from  0  to  255  using  only  eight  bits.  We'll  see  how  this  is  done 
in  a  minute. 

A  byte — able  to  "hold"  256  different  numbers — gives  us 
enough  room  to  assign  all  26  letters  of  the  alphabet  (and  the 
uppercase  letters,  punctuation  marks,  and  so  on)  so  that  each 
p-j  character  we  might  want  to  print  will  have  its  own  particular 

-  •  number.  The  letter  A  (uppercase)  has  been  assigned  the  num- 

ber 65  (in  the  standard  ASCII  code  that  computers  use  to 
r— \  communicate).  The  letter  B  is  66,  and  so  on.  Most  micro- 

'    s  computers,  however,  do  not  adhere  strictly  to  the  ASCII  code, 

except  when  they  are  communicating  with  other  computers, 
I— I  for  example,  through  telephone  links.  The  128  uses  the  code 

'    '<  in  Appendix  G  for  its  internal  operations.  It's  pretty  close  to 

standard  ASCII. 

The  ASCII  code,  an  assignment  of  numbers  to  letters  and 
symbols,  forms  a  convention  by  which  computers  worldwide 
can  communicate  with  each  other.  Text  can  be  sent  via 
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modems  and  telephone  lines,  and  it  will  arrive  meaning  the  \    j 

same  thing  to  an  alien  computer.  It's  important  to  visualize  ' — ' 

each  byte,  then,  as  being  eight  bits  ganged  together  and  that  a 
byte  is  able  to  represent  256  different  things.  As  you  might  (    { 

have  suspected,  256  is  another  power  of  two  (two  to  the  ' — l 

power  of  eight). 

So  these  groupings  of  eight,  these  bytes,  are  a  major  as-  \    \ 

pect  of  computing;  but  we  also  want  to  simplify  our  counting  ' — ' 

from  0  to  255.  We  want  the  numbers  to  line  up  in  a  column 
on  screen  or  on  paper.  Obviously,  decimal  numbers  are  erratic: 
The  number  5  takes  up  one  space,  the  number  230  takes  up 
three  spaces.  Hex  numbers  between  0  and  255  will  always, 
predictably,  take  up  two  spaces  (here's  0-255  expressed  in  the 
hexadecimal  format:  $00-$FF). 

In  addition  to  being  easier  to  format  in  printouts,  hex  is 
also  somewhat  easier  to  visualize  in  terms  of  the  binary  num- 
ber system — the  on/off,  single-bit  way  that  the  computer 
manipulates  numbers: 

Decimal  Hex  Binary 

1  01  00000001 

2  02  00000010 

3  03  00000011(1+2) 

4  04  00000100 

5  05  00000101  (4+1) 

6  06  00000110  (4+2) 

7  07  00000111(4+2+1) 

8  08  00001000 

9  09  00001001  (8  +  1) 
10      (Note  new  digits) ^  0A  00001010  (8 + 2) 

H  0B  00001011  (8+2+1) 

12  0C  00001100(8+4)  ,     , 

13  0D  00001101(8+4+1)  U 

14  0E  00001110  (8+4+2) 

15  OF  00001111  (8+4+2+1) 

16  (Note  new  column •- 10       00010000  I    | 

17  in  the  hex)  11       00010001(16+1)  ^ 

See  how  hex  $10  (hex  numbers  are  usually  preceded  by  a 

dollar  sign  to  show  that  they  are  not  decimal)  looks  like  bi-  1 ' 

nary?  If  you  split  a  hex  number  into  two  parts,  1  and  0,  and 

the  equivalent  binary  number  into  two  parts,  0001  and  0000, 

you  can  see  the  relationship.  j_J 
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p~i  The  Rationale  for  Hex  Numbers 

'  Many  ML  programmers  like  to  use  hexadecimal  numbers  be- 

cause they  are  a  superior  visual  symbol  of  the  manipulations 
J—"]  inside  the  computer;  hex  is  simply  more  like  binary  because 

1  hex  is  a  power  of  two  and  decimal  (base  ten)  is  not  a  power  of 

two.  It's  really  up  to  you  whether  or  when  you  add  hex  to 
your  bag  of  tricks.  (In  the  early  days  of  programming,  another 
base — base  eight — called  octal  was  very  popular.  It's  still  used 
today  when  programming  some  large  computers.)  You  will  see 
that  you  can  choose  to  use  hex  or  decimal  when  writing  ML 
with  the  LADS  assembler  in  this  book.  And  you  can  use  them 
interchangeably,  even  on  the  same  line  of  program  code.  You 
can  write  LDA  $0A  or  LDA  10,  whichever  you  prefer. 

Here's  what  it  looks  like  when  you  count  up  from  zero  in 
both  systems: 

Decimal 

0123456789 

And  now  you  start  over  by  moving  to  a  new  column  with  the 
number  10. 

Hex 

00  01  02  03  04  05  06  07  08  09  0A  0B  0C  0D  0E  OF 

And  then  you  start  over  with  $10,  $11,  and  so  on. 

See  how  we  ran  out  of  digits  when  trying  to  count  up  to 
16  in  hex?  Hex  substitutes  the  first  few  letters  of  the  alphabet 
to  count  past  09. 

The  first  thing  to  notice  is  that  instead  of  the  familiar  deci- 
mal symbol  10,  hex  uses  the  letter  A  because  this  is  where  we 
run  out  of  symbols  and  must  start  over  again  with  a  1  and  a  0. 
Zero  always  reappears  at  the  start  of  each  new  grouping  in  any 
number  system:  0,  10,  20,  and  so  on.  The  same  thing  happens 
with  the  groupings  in  hex:  0,  10,  20,  30,  ...  The  difference  is 
that,  in  hex,  the  1  in  the  "10's"  column  is  actually  what  we 
would  call  a  16  (in  our  normal  decimal  way  of  counting). 

The  second  column  is  now  a  16's  column;  11  (hex)  means  17 
(decimal),  and  21  means  33  (2  times  16  plus  1).  Learning  hex 
is  probably  the  single  biggest  hurdle  to  overcome  when  get- 
ting to  know  ML. 

Don't  be  discouraged  if  it's  not  immediately  clear  what's 
going  on.  (It  probably  never  will  be  totally  clear — hex  is,  after 
all,  unnatural.)  And  remember  that  hex  is  an  option,  not  a 
requirement,  when  programming  in  ML. 
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It's  just  that  much  ML  printed  in  magazines  and  books  , 

uses  hex.  That's  why  you  at  least  need  to  be  able  to  recognize  ! I 

what  it  means.  Nobody  really  knows  it  that  well.  Most  ML 
programmers  use  one  of  the  calculators  sold  by  Sharp,  TI,  or  ,    , 

Hewlett-Packard  that  perform  hex/decimal  conversions.  Also,  I I 

you  can  give  a  decimal  number  to  the  128  in  monitor  mode 

and  it  will  print  the  hex,  octal,  and  binary  versions  of  the  same  ,     > 

number.  Just  precede  the  number  with  a  plus  sign  (+).  For  ex-  i I 

ample,  to  see  versions  of  100,  type  +100  and  press  RETURN. 
You  can  translate  a  hex  number  into  decimal  by  preceding  it 
with  a  dollar  sign  ($)  and  pressing  RETURN.  If  you  happen  to 
be  in  BASIC  mode,  writing  some  LADS  source  code,  you  can 
use  ?HEX$(15)  to  get  the  hex  of  15  or  ?DEC("0F")  to  get  the 
decimal  of  $0F.  Ultimately,  though,  hex  is  one  of  those  things, 
like  telephone  books  and  dictionaries,  that  you  have  to  know 
how  to  use,  but  you  don't  have  to  memorize. 

It's  possible  that  someday  hex  will  go  the  way  of  octal> 
and  we'll  stick  to  the  easy,  obvious  decimal  mode  entirely  (ex- 
cept for  excursions  into  binary  numbers  from  time  to  time).  If 
you  want  more  understanding,  you  might  want  to  practice  the 
exercises  at  the  end  of  this  chapter.  As  you  work  with  hex,  it 
will  gradually  seem  less  and  less  alien. 

To  figure  out  a  hex  number,  multiply  the  second  column 
by  16,  and  add  the  other  number  to  it.  So,  $2 A  would  be  2 
times  16  plus  10  (recall  that  A  stands  for  10). 

Hex  does  seem  impossibly  confusing  when  you  come 
upon  it  for  the  first  time.  It  will  never  become  second  nature, 
but  it  should  be  at  least  generally  understood.  You  need  not 
memorize  hex  beyond  learning  to  count  from  1  to  16;  this 
teaches  you  the  symbols.  Be  able  to  count  from  00  up  to  OF. 
(By  convention,  even  the  smallest  hex  number  is  listed  as  two  , 

digits  as  in  03  or  0B.  The  other  distinguishing  characteristic  is  ' / 

the  dollar  sign  that  is  usually  placed  in  front  of  the  digits:  $05 

or$0E.)  ,     , 

It's  enough  to  know  what  hex  numbers  look  like  and  be  ]_J 

able  to  find  them  when  you  need  them. 

The  First  255  j_| 

Another  thing  that  makes  all  this  easier  is  that  if  you  do  need 

to  work  with  hex,  most  ML  programming  involves  working  ( 

with  hex  numbers  only  between  0  and  255.  This  is  because  a  j ) 

single  byte  (eight  bits)  can  hold  no  number  larger  than  255. 
Manipulating  numbers  larger  than  255  is  of  no  real  importance 

16 


U 


n 

H 


n 


n 
n 


Chapter  2 


[— ]  in  ML  programming  until  you  are  ready  to  work  with  more 

'  advanced  ML  programs.  This  comes  later  in  the  book.  For  ex- 

ample, all  8502  ML  instructions  are  coded  into  one  byte,  all 
|— I  the  flags  are  held  in  one  byte,  and  many  addressing  modes 

'  use  one  byte. 

To  learn  all  we  need  to  know  about  hex  for  now,  we  can 
try  some  problems  and  look  at  some  ML  code  to  see  how  hex 
is  used  in  the  majority  of  ML  work.  But  first,  let's  take  an 
imaginary  flight  over  computer  memory.  Let's  get  a  visual 
sense  of  what  bits  and  bytes  and  the  inner  workings  of  the 
computer's  RAM  look  like. 

The  City  of  Bytes 

Imagine  a  city  with  a  single  long  row  of  houses.  It's  night. 
Each  house  has  a  peculiar  Christmas  display:  On  the  roof  is  a 
row  of  eight  lights.  The  houses  represent  bytes;  each  light  is  a 
single  bit  (Figure  2-1). 

If  we  fly  over  the  City  of  Bytes,  at  first  we  see  only  dark- 
ness. Each  byte  contains  nothing  (zero),  so  all  eight  of  its 
bulbs  are  off.  (On  the  horizon  we  can  see  a  glow,  however, 
because  the  computer  has  memory  up  there,  called  ROM 
memory,  which  is  very  active  and  contains  built-in  programs.) 
But  we  are  down  in  RAM,  our  free  user-memory,  and  there 
are  no  programs  in  RAM  yet,  so  every  house  is  dark.  Let's  ob- 
serve what  happens  to  an  individual  byte  when  different  num- 
bers are  stored  there;  we  can  randomly  choose  byte  1504.  We 
hover  over  that  house  to  see  what  information  is  "contained" 
in  the  light  display: 


H 

i— I  Like  everywhere  else  in  the  City  of  Bytes,  this  byte  is 

i     i  dark.  Each  bulb  is  off.  Observing  this,  we  know  that  the  byte 

here  is  "holding,"  or  representing,  a  zero.  If  someone  at  the 
-— .  computer  types  in  POKE  1504,1,  suddenly  the  rightmost  light 

i     I  bulb  goes  on  and  the  byte  holds  a  one  instead  of  a  zero: 
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This  rightmost  bulb  is  the  one's  column  (so  far,  this  is  ex- 
actly the  way  things  would  work  in  our  usual  way  of  counting 
by  tens,  our  familiar  decimal  system).  But  the  next  bulb  is  in 
the  two's  column,  so  POKE  1504,  2  would  be: 


And  three  would  be  one  and  two: 


ayrBwaa 


In  this  way — by  checking  which  bits  are  turned  on  and 
then  adding  them  together — the  computer  can  look  at  a  byte 
and  know  what  number  is  there.  Each  light  bulb,  each  bit,  is 
in  its  own  special  position  in  the  row  of  eight  and  has  a  value 
twice  the  value  of  the  one  just  before  it: 

ft' 


128*  64*  #*    1^     8*      4*     #     /'* 


Eight  bits  together  make  a  byte.  A  byte  can  hold  a  num- 
ber from  0  through  255  decimal.  We  can  think  of  bytes, 
though,  in  any  number  system  we  wish — in  hex,  decimal,  or 
binary.  Because  the  computer  uses  binary,  it's  useful  to  be  able 
to  visualize  it.  Hex  has  its  uses  in  ML  programming.  And  deci- 
mal is  familiar.  But  a  number  is  still  a  number,  no  matter  what 
we  call  it.  After  all,  five  pennies  are  always  five  pennies, 
whether  we  symbolize  them  by  5  (decimal)  or  $05  (hex)  or 
00000101  (binary)  or  just  call  them  a  nickel. 

A  Binary  Quiz 

BASIC  doesn't  understand  numbers  expressed  in  hex  or  bi- 
nary. Binary,  for  humans,  is  very  visual.  It  forms  patterns  out 
of  zeros  and  ones  and  lets  you  see  an  x-ray  of  the  interior  of  a 
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byte.  The  following  program  will  let  you  quiz  yourself  on  ,     , 

these  patterns.  I > 

Here  is  a  game  which  will  show  you  a  byte  as  it  looks  in 
binary.  You  then  try  to  give  the  number  in  decimal: 


Program  2-1.  Binary  Quiz 


1  10 

5   17 

8  19Q 

?,  15 

f.        39 

9     ?55 

3   5 

7  198 

m  9R4 

A     1* 

u 


10  REM  BINARY  QUIZ  \   | 

20  CI  =  49:C0  =48  < — ) 

30  X  =  INT(256  *  RND  (1)):D  =  X:P  =  128 

40  PRINT "{CLR}" 

50  FOR  I  =  1  TO  8 

60  IF  INT(D  /  P)  =  1  THEN  PRINT  CHR?(C1);:D  =  D  - 

{ SPACE }P:GOTO  80 
70  PRINT  CHR$(C0) ; 
80  P  =  P  /  2:NEXT  I:PRINT 

90  PRINT "WHAT  IS  THIS  IN  DECIMAL? ": PRINT 
100  INPUT  Q:IF  Q  =  X  THEN  PRINT "CORRECT ": GOTO  120 
110  PRINT "SORRY,  IT  WAS"X 
120  FOR  T  =  1  TO  1000:NEXT  T 
130  GOTO  30 

This  next  program  will  print  out  an  entire  table  of  binary 
numbers  from  0  through  255. 

Program  2-2.  Binary  Table 

100  REM  COMPLETE  BINARY  TABLE 

120    FOR  X   =   0    TO    255:PRINTX; 

130    Z   =   X:L   =    7 

140    FOR   Q  =    0    TO   7:T   =    INT    (X   /    2) 

150    K$(L)    =    CHR$(48    +    (X   -   T    *    2)) 

160    L    =   L   -    1:X    =   T:NEXT   Q 

170    X   =    Z 

180    PRINT    TAB(10); 

190    FOR   I   =    0   TO    7:PRINT   K$(I);:NEXT    I  ,      i 

200    PRINT  I I 

210    NEXT   X 

\     I 

Examples  and  Practice 

Here  are  several  ordinary  decimal  numbers.  Try  to  work  out 

the  hex  equivalent:  j>   j 
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We  are  not  making  an  issue  of  learning  hex  or  binary.  If 
you  used  your  monitor  to  get  the  answers,  fine.  As  you  work 
with  ML,  you  will  familiarize  yourself  with  some  of  the  com- 
mon hex  numbers.  And  remember,  you  can  program  in  ML 
without  needing  to  worry  about  hex  numbers.  For  now,  we 
only  want  to  be  able  to  recognize  what  hex  is.  The  LADS 
assembler  or  the  128's  built-in  monitor  will  do  the  translations 
for  you  any  time  you  need  them. 

One  other  reason  that  we're  not  stressing  hex  too  much  is 
that  ML  is  generally  not  programmed  without  the  help  of  an 
assembler.  LADS  will  handle  your  input  automatically.  It  al- 
lows you  to  choose  whether  you  prefer  to  program  in  hex  or 
decimal.  With  LADS,  just  use  the  $  symbol  when  you  intend  a 
number  to  be  interpreted  as  hex.  Otherwise,  LADS  will  as- 
sume you  mean  decimal. 

This  short  BASIC  program  is  good  for  practicing  hex  and 
also  shows  you  how  a  two-byte  hex  number  relates  to  a  one- 
byte  hex  number.  It  will  take  decimal  in  and  give  back  the 
correct  hex. 

Program  2-3.  Hex  Practice 

10  PRINT" tCLR}" 

20  INPUT"ENTER  A  DECIMAL  NUMBER" ;X 

30  IF  X>  255  THEN  20: REM  NO  NUMBERS  BIGGER  THAN  25 

5  ALLOWED 
40  PRINT  "S";RIGHT$(HEXS(X),2) 
50  PRINT:GOTO  20 

For  larger  hex  numbers  (up  to  two  bytes,  $FFFF  equals 
65535),  we  can  just  make  a  simple  change  to  Program  2-3. 
Change  line  30  to  IF  X  >  65535  THEN  20,  and  change  line  40 
to  PRINT  "$";HEX$(X).  This  will  give  us  four-place  hex  num- 
bers. These  larger  hex  numbers  are  used  in  ML  mainly  for  ad- 
dresses, since  the  8502  can  directly  address  65536  bytes  (bytes 
with  addresses  from  0  through  65535).  This  is  the  reason  that 
many  microcomputers  max  out  at  64K.  There  are  special  ways 
to  get  around  this,  but  an  eight-bit  microprocessor  like  the 
8502  is  generally  limited  in  the  total  amount  of  RAM  memory 
it  can  access  directly. 

The  number  65535  is  interesting  because  it  represents  the 
limit  of  our  computers'  memories.  The  128  has  additional 
ROM  and  RAM  in  banks  which  we'll  discuss  later.  The  128 
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can  directly  address  only  64K  at  any  one  time,  but  it  can  ,    j 

quickly  switch  banks  in  and  out  so  that  it  appears  to  address  I > 

more  than  65535  bytes  at  once.  But  64K  is  the  upper  limit  of 

direct  addressing  without  bank  switching  because  the  8502  ■     t 

chip  is  designed  to  be  able  to  address  (put  bytes  in  or  take  i I 

them  out  of  memory  cells)  only  up  to  $FFFF  (65535). 

Ganging  Two  Bytes  Together  to  Form  an  Address  i ) 

The  8502  often  addresses  by  attaching  two  bytes  together  and 
looking  at  them  as  if  they  formed  a  unit.  It's  like  the  way  that 
putting  eight  bits  together  forms  the  unit  we  call  a  byte.  The 
largest  number  that  two  bytes  can  represent  is  $FFFF  (65535), 
and  the  most  that  one  byte  can  represent  is  $FF  (255).  Three- 
byte  addressing  is  not  possible  for  the  8502  chip.  Machine  lan- 
guage means  programming  instructions  which  are  understood 
directly  by  the  8502  chip  itself.  There  are  other  CPU  (Central 
Processing  Unit)  chips,  but  the  8502  is  the  128's  CPU  that's 
covered  in  this  book. 

Reading  a  Machine  Language  Program 

Before  getting  into  an  in-depth  look  at  the  monitor,  that  bridge 
between  you  and  your  machine's  language — we  should  first 
learn  how  to  read  ML  program  listings.  You've  probably  seen 
them  often  enough  in  magazines. 

These  commented,  labeled,  but  very  strange-looking  pro- 
grams are  called  source  code  (see  Program  2-7  for  an  example). 
Source  code  is  what  you  write  when  you  want  to  create  an 
ML  program.  It  can  be  translated  by  an  assembler  program  (like 
LADS)  into  an  ML  program.  When  you  have  an  assembler 
program  attack  your  source  code,  it  looks  at  the  keywords  (the 
instructions  and  their  arguments,  and  their  addresses)  and  ( 

then  POKEs  a  series  of  numbers  into  the  computer.  This  series  | | 

of  numbers  is  called  the  object  code  and  is  the  runnable  ML 

program.  You  can  CALL  object  code  and  it  will  do  whatever 

you've  designed  it  to  do.  i | 

Source  code  usually  contains  a  great  deal  of  information 
in  the  form  of  comments  which  are  of  interest  to  the  pro-  ( 

grammer,  but  which  the  computer  ignores.  It's  rather  like  the  { j 

way  a  BASIC  program  has  REMarks  to  which  the  computer 
pays  no  attention. 

The  computer  needs  only  a  list  of  numbers  which  it  can  ( j 

execute  in  order.  That's  what  an  ML  program  is.  But  for  most 
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<*""]  people,  lists  of  numbers  are  only  slightly  more  understandable 

'  than  Morse  code.  The  solution  is  to  let  us  use  words  which  are 

then  translated  into  numbers  for  the  computer.  The  primary 
r— i  job  of  an  assembler  is  to  recognize  an  ML  instruction.  These 

'    '  instructions  are  called  mnemonics,  which  means  "memory 

aids."  They  are  like  BASIC  words  except  that  they  are  always 
three  letters  long  and  are  somewhat  less  like  standard  English. 
If  you  type  the  mnemonic  instruction  JMP,  the  assembler 
POKEs  a  76  into  RAM  memory.  It's  easier  for  us  to  remember 
something  like  JMP  than  the  number  76.  Seeing  a  76,  how- 
ever, the  computer  immediately  knows  that  it's  supposed  to 
perform  a  JMP.  The  number  76  is  an  operation  code,  or  opcode, 
to  the  computer. 

We  write  the  mnemonic  instruction  JMP,  an  assembler 
translates  this  into  the  number  76,  and  the  computer  rec- 
ognizes 76  as  the  command  JUMP.  These  three-letter  words 
we  use  in  ML  programming  were  designed  to  sound  like  what 
they  do.  JMP  does  a  JUMP  (like  a  GOTO  in  BASIC).  Deluxe 
assemblers  like  LADS  also  let  you  use  labels  instead  of  num- 
bers. These  labels  can  refer  to  individual  memory  locations, 
special  values  like  the  score  in  a  game,  or  entire  subroutines. 
(See  the  instructions  for  LADS  in  Appendix  B  for  more  infor- 
mation about  using  labels.) 

Four  Ways  to  List  a  Program 

Labeled,  commented  source  code  listings  are  the  most  elabo- 
rate kind  of  ML  program  representation.  There  are  also  three 
other  kinds  of  ML  listings  you  might  come  across.  Let's  see 
how  these  four  styles  of  representing  an  ML  program  would 
look  by  using  a  simple  example  program  that  just  adds  2  +  5 
f— j  and  stores  the  result  in  RAM  memory  location  848.  The  first 

'    >  two  styles  are  simply  ways  for  you  to  type  a  program  into  the 

computer.  The  last  two  styles  show  you  what  to  type  in,  but 
also  illustrate  what  is  going  on  in  the  ML  program.  First,  let's 
look  at  the  most  elementary  kind  of  ML  found  in  books  and 
magazines:  the  BASIC  loader. 

Program  2-4  BASIC  Loader 

10  FOR  ADDRESS  =  2816  TO  2824 

20  READ  BYTE 

30  POKE  ADDRESS,  BYTE 

40  NEXT  ADDRESS 

50  DATA  24,169,2,105,5,141,80,3,96 
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This  is  a  series  of  decimal  numbers  in  DATA  statements  i     i 

which  are  POKEd  into  memory  beginning  at  decimal  address  ' — I 

2816  (or,  expressed  as  hex,  $B00).  This  is  a  BASIC  program. 
When  you  run  this  program,  these  numbers  are  stashed  into  i    j 

RAM,  and  they  form  a  little  ML  routine  which  clears  the  carry  ' — > 

(so  there  won't  be  any  holdover  from  previous  addition — you 
always  clear  the  carry  before  any  addition  in  ML),  then  puts  i    , 

the  number  2  into  the  accumulator — a  special  location  in  the  » — > 

computer  that  we'll  get  to  later — and  then  adds  5.  The  result 
of  the  addition  is  then  copied  from  the  accumulator  into  deci- 
mal address  848.  If  you  try  this  program  out,  you  can  SYS 
2816  to  execute  the  ML  program  and  then  PRINT  PEEK  (848) 
and  you'll  see  the  answer:  7.  BASIC  loaders  are  convenient  for 
magazines  to  publish  because  the  user  doesn't  need  to  know 
anything  at  all  about  ML  to  enter  and  use  the  ML  programs. 
The  BASIC  loader  POKEs  the  ML  program  into  memory,  and 
then  the  only  thing  the  user  has  to  do  is  SYS  to  the  right  ad- 
dress and  the  ML  transfers  control  back  to  BASIC  when  its  job 
is  done.  Many  ML  programs  end  with  an  RTS  (ReTurn  from 
Subroutine)  instruction  which  causes  the  computer  to  revert  to 
BASIC  mode  after  the  ML  program  has  finished. 

Getting  even  closer  to  the  machine  level  is  the  second 
way  you  might  see  ML  printed  in  books  or  magazines:  the  hex 
dump.  The  128  has  a  special  monitor  program  in  ROM  which 
lets  you  list  memory  addresses  and  their  contents  as  hex 
numbers. 

More  than  that,  with  the  monitor  you  can  type  in  new 
numbers  and  change  the  program.  That's  what  a  hex  dump 
listing  is  for.  You  copy  its  numbers  into  your  computer's  RAM 
by  using  your  computer's  monitor.  (The  monitor  is  so  im- 
portant to  ML  programming  that  we'll  spend  all  of  Chapter  3               ,     , 
exploring  what  it  can  do  for  us.)  1 I 

A  hex  dump,  like  a  BASIC  loader,  tells  you  nothing  about 
the  functions  or  strategies  employed  within  an  ML  program. 

Program  2-5  is  the  hex  dump  version  of  the  same  2  +  5 
addition  program. 

The  third  type  of  listing  is  called  a  disassembly.  It's  the  op- 
posite of  an  assembly:  A  program  called  a  disassembler  takes  1 I 

machine  language  (the  series  of  numbers,  the  opcodes  in  the 
computer's  memory)  and  translates  it  into  the  words,  the 
mnemonics,  which  humans  can  read  and  understand.  The  in- 
struction (the  mnemonic)  you  use  when  you  want  to  put  some- 
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<—"|  thing  into  the  accumulator  is  called  LDA,  and  you  store  what's 

'    '  in  the  accumulator  by  using  an  STA.  We'll  get  to  them  later. 

In  this  version  of  our  addition  routine,  Program  2-6,  it's  a 
bit  clearer  what's  going  on  and  how  the  program  works.  No- 
tice that  on  the  far  left  we  have  the  memory  addresses  (in 
hex),  then  hex  numbers  representing  the  actual  bytes  of  the 
program  and,  on  the  right,  the  translation  into  ML  instruc- 
tions. ADC  means  ADd  with  Carry  and  RTS  means  ReTurn 
from  Subroutine.  A  disassembly  is  to  ML  what  LIST  is  to 
BASIC.  Your  monitor  has  a  disassembler  built-in  which  will 
produce  these  listings. 

The  Deluxe  Version 

Finally,  we  come  to  that  full,  luxurious,  commented,  labeled, 
deluxe  source  code  we  spoke  of  earlier.  Program  2-7  includes 
the  hex  dump  and  the  disassembly,  but  it  also  has  labels  and 
comments  and  line  numbers  added  to  further  clarify  the  pur- 
poses of  things  and  to  make  it  easier  for  programmers  to  enter 
and  edit  their  programs.  This  kind  of  listing  can  be  produced 
with  the  LADS  assembler  by  invoking  the  .S  or  .P  features  to 
create  a  full  listing  on  screen  or  printer  during  the  assembly 
process. 

Note  that  in  Program  2-7  all  the  numbers  (except  the  line 
numbers  on  the  far  left)  are  in  hex.  LADS  makes  this  optional. 
To  make  them  decimal,  use  the  .NH  option  and  your  listing 
will  be  entirely  in  decimal. 

On  the  far  left  are  the  line  numbers  for  the  convenience 
of  the  programmer  when  writing  the  source  code  (the  program 
you  write  to  feed  into  the  assembler).  The  line  numbers  can  be 
used  the  way  BASIC  line  numbers  are  used:  deleted,  inserted, 

n  and  so  on.  Next  are  the  memory  addresses  where  each  in- 

dividual instruction  in  this  routine  is  located  in  RAM.  Then 
come  the  hex  numbers  of  the  instructions.  (So  far,  it  resembles 

[""]  the  traditional  hex  dump.)  Next  are  the  disassembled  transla- 

tions of  the  hex,  but  note  that  you  can  replace  numbers  with 
labels  as  we'll  see  in  Program  2-8.  Last  are  the  comments. 

r~]  They  are  the  same  as  REM  statements  in  BASIC. 

Program  2-8  is  functionally  the  same  as  2-7,  but  we've 
defined  some  labels  and  used  them  instead  of  numbers.  That 
can  be  a  good  way  to  remember  the  purpose  of  various  things, 
just  the  way  variable  names  in  BASIC  assist  the  programmer. 
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3. 

05 

8. 

81 

4. 
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Where  Programs  2-7  and  2-8  show  you  what  LADS  prints  j    I 

out  during  an  assembly  if  you  request  a  listing,  Program  2-9  ' — ' 

illustrates  just  the  source  code  part,  what  you  would  type  into 
your  128  prior  to  assembly.  Source  code  is  the  program  you  \    i 

write;  it's  what's  fed  to  the  assembler  to  produce  object  code  *■ — ' 

(the  runnable  ML  program.)  The  object  code  has  not  yet  been 
generated  from  this  source  code.  The  code  has  not  been  assetn-  i    j 

bled  yet.  You  can  save  or  load  source  code  in  the  same  way  ' — ' 

that  you  can  save  or  load  programs  via  BASIC.  Once  Program 
2-9  is  typed  in,  you  could  SYS  10000  (if  you'd  previously 
loaded  LADS  into  memory),  and  LADS  would  translate  the 
instructions  and  print  them  on  the  screen  and/or  POKE  them 
into  memory  if  so  instructed. 

Those  few  differences  between  Programs  2-8  and  2-9  are 
conveniences  for  the  programmer.  The  *=  symbol  tells  the 
assembler  where  you  want  the  ML  program  located  in  mem- 
ory. The  .P  turns  on  the  printer,  and  .S  turns  on  listing  to 
screen  during  assembly.  The  semicolons  announce  that  a  re- 
mark follows  and  the  assembler  should  ignore  the  rest  of  the 
line,  just  like  REM  in  BASIC. 

A  simple  assembler,  like  the  one  found  in  the  128's  mon- 
itor, operates  differently.  It  translates,  prints,  and  POKEs  as 
soon  as  you  hit  RETURN  on  each  line  of  code.  You  can  save 
and  load  the  object,  but  not  source  code,  with  this  simple 
assembler. 

Before  we  get  into  the  heart  of  ML  programming,  a  study 
of  the  opcodes  and  ways  of  moving  information  around 
(called  addressing),  we  should  look  at  that  major  ML  program- 
ming aid:  the  monitor.  It  deserves  its  own  chapter. 
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A  monitor  is  a  program  which  allows  you  to  work  directly 
with  your  computer's  memory.  When  you  "go  below"  BASIC 
into  the  monitor  mode,  BASIC  is  no  longer  active.  If  you  type 
RUN,  it  will  not  execute  anything.  BASIC  commands  are  not 
recognized.  The  computer  waits,  as  usual,  for  you  to  type  in 
some  instructions.  There  are  only  a  few  instructions  to  give  to 
a  monitor.  When  you're  working  with  it,  you're  pretty  close  to 
talking  directly  to  the  machine  in  machine  language. 

The  128  has  a  monitor  in  ROM.  This  means  that  you  do 
not  need  to  load  the  monitor  program  into  the  computer;  it's 
always  available  to  you.  You  can  use  hex,  decimal,  or  binary 
numbers  with  the  monitor.  Signify  hex  as  usual  with  $  before 
the  number  and  use  %  before  binary  numbers.  However,  you 
don't  need  to  use  the  $  when  giving  an  address  for  disassembly 
or  assembly,  or  a  range  of  addresses  for  hunting,  and  so  forth. 
Hex  is  assumed  in  these  cases  as  the  default  condition. 

Also,  you  can  specify  any  memory  bank  by  giving  its 
number  before  the  actual  address  number.  For  example,  M 
3000  will  show  you  what's  in  address  3000  (hex)  and  beyond 
of  bank  0  (always  the  default  bank).  To  see  memory  in  bank  1 
you  would  type  M  13000. 

Debugging  is  the  main  purpose  of  a  monitor.  You  use  it  to 
check  your  ML  code  to  find  errors.  Some  computer  manufac- 
turers, Apple,  for  instance,  even  call  their  monitor  a  debugger. 

You  enter  the  128  monitor  by  hitting  the  F8  key  (SHIFT- 
F7).  You  will  see  the  registers  displayed  and  the  cursor  below 
the  display.  Here  are  the  monitor  instructions: 

1.  Assemble 

A  (address)  (mnemonic)  (argument)  will  assemble  a  line  of  source 
code. 

Example:  2000  LDA  #$15 

will  assemble  that  at  address  02000.  Remember  that  anytime 
you  want  to  access  memory  banks  other  than  bank  0,  you  can 
type  the  bank  number  before  the  actual  memory  address.  If 
you  want  to  assemble  to  bank  1,  address  2000,  you  would 
type  12000  LDA  #$15. 
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If  you  make  a  mistake,  a  question  mark  (?)  will  appear  on 
the  line.  As  always,  you  can  cursor  up  and  correct  your  mis- 
take; RETURN  always  enters  each  line.  Also,  like  auto- 
numbering,  the  next  address  for  assembly  will  automatically  j  f 
appear  on  the  line  below,  so  you  need  specify  the  address  4 — > 
only  when  you  first  start  assembling. 

You  can  also  use  the  period  (.)  to  signify  assembly.  The  ^    j 

monitor  prints  periods  at  the  start  of  each  line.  ' — ' 

This  mini-assembler  cannot  use  labels  and  has  other 
drawbacks.  However,  it's  a  fine  tool  for  testing  small  ideas,  a 
few  lines  long,  and  for  making  little  adjustments  to  a  larger 
program  while  debugging. 

2.  Compare  memory 

C  {start  of  block)  {end  of  block)  {start  of  second  block) 

To  see  whether  two  sections  of  memory  are  identical  or 
which  bytes  differ,  you  type  C  followed  by  the  start  and  end 
address  of  the  first  block  (which  lets  the  assembler  also  cal- 
culate the  length  of  the  blocks  being  compared)  and  then  give 
the  address  of  the  start  of  the  second  block. 

Example:  C  1000  1020  4000 

This  will  print  the  addresses  of  any  bytes  which  do  not 
match  when  the  blocks  of  memory  between  1000-1020  and 
4000-4020  are  compared.  This  facility  can  be  useful  if  you 
want  to  see  where  two  versions  of  the  same  routine  differ.  If, 
for  example,  version  5  of  the  game  you're  writing  always 
works,  but  version  6  turns  the  screen  black,  you  can  load  the 
two  versions  into  memory,  targeting  one  of  them  to  a  different 
location  in  memory  (see  a  special  feature  of  Load  described 
below),  and  then  compare  them  to  see  where  they  differ. 
Alternatively,  you  could  use  a  BASIC-Aid  type  program  to  j    J 

compare  their  source  codes.  When  possible,  that's  the  pre- 
ferred method. 

3.  Disassemble  Lj 

D  {start  address)  {optional  end  address) 

This  allows  you  to  see  the  ML  equivalent  of  a  program  \    ' 

listing  in  BASIC.  Raw  object  code  in  memory  will  be  printed  L- -* 

to  the  screen  in  a  readable,  rough  source  code  form,  as  it  ap- 
pears when  you  type  in  source  code  using  A  (Assemble)  de- 
scribed above.  There  still  won't  be  labels,  but  you  can 
interpret  what  a  piece  of  code  does. 
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D,  like  M  described  below,  can  simply  be  given  a  start  ad- 
dress, in  which  case  it  disassembles  about  20  bytes  and  stops. 
Alternatively,  you  can  give  both  a  start  and  an  end  address, 
whereupon  it  will  scroll  through  the  range  of  memory  re- 
quested. You  can  always  slow  down  the  scrolling  by  holding 
down  the  Commodore  key,  freeze  the  scroll  with  CONTROL-S, 
or  end  the  scroll  with  RUN/STOP. 

Disassembly  is  perhaps  the  single  most  useful  command 
in  the  monitor.  You  will  sometimes  be  trying  out  a  program 
you've  written,  and,  bing  (the  monitor  makes  a  noise  when 
you  enter  it  this  way),  you'll  find  yourself  staring  at  the  reg- 
ister display.  This  means  that  your  program  failed,  but  luckily 
the  computer  didn't  harden  into  immobility  (the  worst  kind  of 
bug  to  fix).  Instead,  you  gained  some  valuable  information: 
You  can  look  at  the  PC  (Program  Counter)  and  see  where  you 
fell  into  monitor  mode  (disassemble  a  few  bytes  before  the  PC 
address  and  you'll  find  the  00  (BRK)  that  sent  you  into  the 
monitor).  Not  only  that,  but  sometimes  the  values  in  the  accu- 
mulator or  Y  or  X  registers  will  be  a  clue  about  what  went  awry. 

In  tough  situations,  where  a  bug  is  enigmatic,  you'll  find 
yourself  following  a  path  through  your  program,  dis- 
assembling until  you  find  a  JSR  or  JMP,  then  disassembling 
the  subroutine  indicated  by  the  JSR,  trying  to  see  where  your 
program  goes  off  the  rails.  One  obvious  case  would  be  if  the 
disassembler  reported  that  it  couldn't  make  sense  of  your  code 
(it  will  print  ???  when  it  cannot  disassemble  something).  This 
probably  means  that  you  typed  in  your  source  code  incorrectly 
($#B0  with  the  #  in  the  wrong  place,  for  example)  which  con- 
fused the  assembler. 

When  debugging  larger  programs,  you'll  be  deliberately 
inserting  BRK  at  key  points  in  the  code  to  force  the  computer 
into  the  monitor  so  that  you  can  examine  the  registers  or  key 
variables  (maybe  your  zero  page  pointers)  in  your  program. 
Here  D  helps  you  discover  which  of  perhaps  several  break- 
points you've  landed  on. 

You  can  also  make  direct  modifications  to  the  code.  You 
can't  change  the  hex  numbers,  the  object  code,  but  you  can 
cursor  over  and  change  the  source  code.  For  example,  .BOO  A9 
00  LDA  #$00  can  be  altered  by  moving  to  the  #$00  and 
changing  it  to,  say,  #$05  and  hitting  RETURN.  Because  the 
period  at  the  start  of  the  line  is  the  same  as  the  A  (Assemble) 
command,  you'll  have  activated  the  mini-assembler. 
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If  you  do  want  to  change  the  object  bytes,  you  can  put  a 
greater-than  symbol  (>)  at  the  start  of  the  line  and  then 
change  the  00  to  05,  but  you  must  get  rid  of  the  LDA  #$00 
which  follows  on  that  line.  The  >  (memory  change)  command 
cannot  make  sense  of  LDA  #$00.  The  fastest  way  to  eliminate 
the  end  of  the  line  is  ESC  then  Q,  one  of  the  128's  convenient 
escape  code  tricks.  Note  that  you  press  ESC,  but  do  not  hold  it 
down  while  pressing  Q.  ^-c-J 

The  reason  we  bother  with  this  Disassemble/Memory 
change  method  is  that  sometimes  you'll  want  to  insert  NOPs 
directly  into  your  program  to  eliminate  something  temporarily 
and  test  the  program  without  it.  Let's  say  that  you  have  a 
change  screen  color  subroutine  at  $3500  and  you  suspect  it 
might  be  what's  crashing  your  program. 

LDA  #$04 
JSR  $3500 
LDY  #$03 

might  be  a  segment  of  your  program.  You  could  disassemble 
this,  insert  EA  EA  EA  over  the  20  00  35  which  represented 
your  jump  to  that  suspect  subroutine,  and  then  rerun  your 
program.  EA  is  the  code  for  NOP,  NO  oPeration.  It  does  noth- 
ing, so  you've  temporarily  removed  that  entire  subroutine 
from  the  program  you're  testing  (if  this  is  the  only  JSR  to  that 
subroutine).  Alternatively,  you  could  place  a  60  (RTS,  ReTurn 
from  Subroutine)  at  $3500  to  remove  it  from  all  attempts  to 
call  it  throughout  your  program. 

These  and  other  debugging  tricks  will  occur  to  you  as  you 
test  and  work  with  your  programs.  The  Disassemble  function 
will  prove  invaluable. 

It's  also  instructive  to  use  the  disassembler  to  follow  the 
logic  of  the  BASIC  in  your  128.  Try  looking  at  bank  15  j     j 

wherein  BASIC,  I/O,  and  the  Kernal  reside  between  $4000—  ' 

$FFFF.  Just  D  F4000.  To  continue,  type  D  RETURN  repeat- 
edly. Around  F41C0  you'll  start  to  see  lots  of  ???  which  means 
it's  likely  to  be  a  table  of  some  sort.  Switch  to  M  F41C0  to  see 
the  meaning  of  this  section.  See  if  you  can  locate  the  BASIC 
keywords. 

Because  it's  such  a  valuable  tool,  let's  briefly  review  the 
elements  of  disassembly.  A  disassembly  will  contain  three  fields 
(a  field  is  a  "zone"  of  information).  The  first  field  will  contain 
the  address  of  an  instruction  (in  hex).  The  address  field  is 
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somewhat  comparable  to  BASIC'S  line  numbers.  It  defines  the 
order  in  which  instructions  will  normally  be  carried  out. 

The  second  field  shows  the  hex  numbers  for  the  instruc- 
tion, and  the  third  field  is  where  a  disassembly  differs  from  a 
"memory"  or  "hex"  dump  (see  Memory  below).  This  third 
field  translates  the  hex  numbers  of  the  second  field  back  into  a 
mnemonic  and  its  argument. 

Here's  an  example  of  a  disassembly: 

2000     A9  41  LDA  #$41 

2002     8D  23    32      STA  $3223 
2005     A4  99  LDY  $99 

Recall  that  a  dollar  sign  shows  that  a  number  is  in  hexa- 
decimal. The  pound  sign  (#)  means  "immediate"  addressing 
(put  the  number  itself  into  the  A  register  at  2000  above). 
Confusing  these  two  symbols  is  a  major  source  of  errors  for 
beginning  ML  programmers. 

You  should  pay  careful  attention  to  the  distinction  be- 
tween LDA  #$41  and  LDA  $41.  The  second  instruction  (with- 
out the  pound  sign)  means  to  load  A  with  whatever  number  is 
found  in  address  $41  hex. 

LDA  #$41  means  put  the  actual  number  41  itself  into  the 
accumulator. 

If  you  are  debugging  a  routine,  check  to  see  that  you've 
got  these  two  types  of  numbers  straight,  that  you've  loaded 
from  addresses  where  you  meant  to  (and,  vice  versa,  that 
you've  loaded  immediately  where  you  intended). 

4.  Fill 

F  (start  address)  (end  address)  (value) 

This  fills  the  zone  between  start  address  and  end  address 
j""]  with  the  byte  value  which  follows.  It's  most  useful  when  try- 

ing to  see  what  areas  of  memory  are  unsafe  to  use,  particularly 
when  you  are  modifying  a  commercial  program  like  a  word 
processor  and  are  unsure  where  it  might  be  storing  variables. 
Load  the  word  processor,  F  0B00  0BFF  00  (filling  the  cassette 
buffer  with  zeros),  and  put  the  word  processor  through  its 
paces.  Then,  enter  the  monitor  and  examine  the  "snow,"  the 
zeros  you  sprayed  there,  to  see  if  any  of  them  changed,  if  the 
word  processor  left  any  tracks.  This  is  a  quick  way  to  find  out 
if  your  use  of  this  buffer  will  conflict  with  the  word  proces- 
sor's need  for  the  same  space. 
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and  wait  a  few  seconds  while  the  monitor  reports  where  it 
finds  matches.  (We  left  off  the  T  in  PRINT  because  BASIC 
stores  its  keywords  with  the  final  letter  "shifted"  by  adding 
128  to  it.  This  is  how  it  knows  the  end,  the  length  of  each 
keyword.)  Then,  use  M  (described  below)  to  see  the  memory 
and  look  at  whatever  you  find. 

Be  sure  to  use  a  single  quotation  mark  to  set  off  a  charac- 
ter string. 
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5.  Go 

G  (address) 

You  can  run  an  ML  program  from  within  the  monitor 
with  the  G  instruction.  The  program  must  end  with  a  BRK  if  ]_J 

you  expect  to  return  to  the  monitor  when  the  program  ends. 
Try  this:  Type  A  BOO  LDA  #$15  and  then  hit  RETURN.  Then 
type  TAY  (and  press  RETURN),  then  BRK  (and  RETURN 
twice).  You've  created  a  little  program  that  puts  $15  into  the 
accumulator,  transfers  it  to  the  Y  register,  and  stops.  Type  R  to 
see  the  condition  of  the  accumulator  and  the  Y  register.  Then 
type  G  BOO  and  see  what  happened  to  the  accumulator  and  Y 
registers. 

Note  that  you  can  Go  to  Mars  if  you  give  G  the  wrong 
address.  If  you've  written  something  lengthy,  you  might  want 
to  first  save  it  with  S  (described  below)  to  be  on  the  safe  side. 
Also,  remember  that  the  ML  must  end  with  a  BRK;  otherwise, 
you  may  be  kicked  out  of  the  monitor  back  into  BASIC  or  the 
program  may  crash  altogether.  For  routines  that  normally  end 
with  RTS,  simply  change  the  RTS  to  BRK  to  use  the  G  instruc- 
tion (remember  to  change  the  BRK  back  to  an  RTS  after 
you've  tested  the  routine).  Or,  if  you  don't  need  the  register 
display  that  G  provides  when  the  program  ends  you  can  use 
the  J  instruction  instead  (see  below). 

6.  Hunt 

H  (start  address)  (end  address)  (pattern) 

This  can  be  useful  when  you're  exploring  a  commercial 
program  or  BASIC  or  even  want  to  find  a  particular  location  in 
your  own  program.  It  will  search  between  the  start  and  end 
addresses  for  a  match  to  the  pattern  you  give  it.  The  pattern 
can  be  a  series  of  hex  numbers  or  a  character  string.  Let's  try  J    j 

locating  BASIC'S  table  of  keywords: 

H  F4000  FFFFF  'PRIN 


}     ( 
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f—|  Here's  another  use  for  H.  Assume  that  you  know  that  a 

certain  pattern  of  bytes  is  going  to  appear  in  BASIC  and  you 
want  to  find  them.  Let's  look  for  all  locations  where  BASIC 

j—" ?  switches  in  ROM  bank  15.  To  get  the  pattern,  type: 

A  BOO  LDA  #0 

STA  $FF00 

/    (  and  you  can  then  see  what  pattern  of  bytes  to  look  for.  So 

now  hunt: 

H  F4000  FFFFF  A9  00  8D  00  FF 

and  then  you  can  disassemble  to  learn  more  about  what's  go- 
ing on  in  your  ROM. 

7.  Jump 

J  (address) 

This  instruction  is  similar  to  G,  but  if  the  ML  program  be- 
ing executed  ends  with  RTS  it  doesn't  break  back  into  the 
monitor  with  a  display  of  registers.  Instead,  it  just  quietly  re- 
turns to  the  monitor  with  no  special  display — just  the  usual 
blinking  cursor.  You  might  want  to  use  J  if  you  are  testing  a 
routine  which  affects  the  screen,  such  as  printing  a  message. 
You'd  get  cleaner  results  with  J  than  G  in  this  case. 

Remember  that  ML  programs  you  run  with  the  J  instruc- 
tion should  end  with  RTS  if  you  want  to  avoid  the  register  dis- 
play. If  the  ML  ends  with  BRK,  the  effect  will  be  the  same  as 
if  you  had  used  the  G  instruction. 

8.  Load 

L  ("filename")  (,8  for  disk  or  ,1  for  tape)  (optional  load  address) 

If  you've  worked  with  ML  on  a  computer  which  has  no 
monitor,  you'll  welcome  the  convenience  of  this  and  Save,  its 
companion  function.  With  L  you  can  retrieve  any  file  from 
tape  or  disk  (it's  like  BASIC'S  BLOAD  command),  and,  even 
more  helpful,  you  can  load  an  ML  program  to  an  address 
which  is  different  from  the  one  whereat  it  normally  resides, 
different  from  the  address  from  which  you  originally  saved  it. 
This  is  a  good  way  to  test  versions  of  a  program  (see  Compare 
above). 

If  you  write  a  program  in  bank  1  and  save  it,  it  will  load 
back  into  bank  0  unless  you  specify  bank  1  in  the  optional 
load  address  field.  Notice,  too,  that  commas  are  necessary 
with  this  command  to  separate  the  argument  fields.  Load  and 
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Save  are  odd  this  way;  you  must  type  L  "FILENAME",8  rather  )    | 

than  L  "FILENAME"  8.  "  ^ 

9.  Memory 

M  (optional  start  address)  (optional  end  address)  J [ 

Among  the  most  useful  of  all  monitor  commands,  this 
memory  display  shows  you  a  visual  display  of  your  memory.  ,    ) 

It's  sometimes  called  a  hex  dump  because  you  will  see  the  1 I 

value  in  each  memory  cell  displayed  as  a  two-character  hex 
digit.  To  the  right,  you'll  see  the  same  bytes  displayed  as 
characters  when  possible.  Unprintable  characters  are  signified 
by  a  period  (.).  You  can  change  any  of  the  bytes  (except  the 
address)  as  long  as  the  >  symbol  appears  at  the  first  position 
in  the  line.  You  can  thus  quickly  check  your  tables  and  vari- 
ables to  see  if  they're  behaving  properly  or  modify  them  for 
testing  purposes. 

If  you  provide  no  argument,  M  will  show  you  the  zone  of 
memory  most  recently  accessed.  If  you  give  a  start  address, 
that's  the  memory  you'll  see.  As  before,  if  you  use  a  number 
like  BOO,  you'll  see  bank  0.  If  you  want  to  specify  another 
bank,  type  its  number  first:  10B00  would  show  you  BOO  in 
bank  1. 

10.  Registers 

R 

This  will  show  you  the  current  status  of  your  registers.  It 
looks  like  this: 

PC    SR  AC  XR  YR  SP 
;    00B09  30    00    05    FF  F9 

The  PC  is  the  program  counter,  the  place  in  memory 
where  you  last  were  when  the  monitor  was  invoked.  Perhaps 
you  had  a  BRK  instruction  which  forced  your  program  to  halt 
so  you  could  test  it.  If  you  have  a  BRK  at  0B07,  the  PC  will 
show  0B09  as  above.  It's  always  two  bytes  past  where  you  ac- 
tually break  for  some  reason.  Just  remember  that  this  is  what 
happens.  You  can  locate  the  BRK  with  Disassemble  described 
above. 

The  SR  is  the  status  register  (the  byte  that  holds  the 
flags).  It's  not  useful  in  this  form  because  it's  too  hard  to  fig- 
ure out  what  flags  are  up  or  down  to  achieve,  as  above,  for  ex- 
ample, a  total  byte  value  of  $30.  The  AC  is  the  accumulator; 
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the  X  and  Y  registers  follow.  The  SP  is  the  stack  pointer.  For- 
get about  it,  too. 

You  can  cursor  over  and  directly  change  the  values  in  the 
AC,  XR,  or  YR,  which  can  be  useful  sometimes  during  testing. 

Note  that  the  monitor  always  supplies  that  first  digit 
signifying  bank  number,  but  for  you  it's  optional.  Most  of  the 
time  you'll  be  in  the  default  bank  0. 

11.  Save 

S  ("filename")  (,8  for  disk  or  ,1  for  tape)  (,start  address)  (,end  address 
plus  one) 

S  saves  a  section  of  memory  to  disk  or  tape,  like  BSAVE. 
The  commas  are  necessary  to  separate  the  fields  as  shown. 
You  could  save  screen  RAM  if  you  wanted  or  anything  else, 
but  the  most  common  use  for  this  is  to  save  ML  programs. 
The  bank  conventions  and  other  rules  described  under  Load 
above  apply  to  Save  as  well. 

Notice,  however,  a  special  oddity  here:  The  end  address 
must  be  one  byte  beyond  the  actual  end  of  your  program.  Again, 
nobody  who  knows  why,  tells,  but  you've  got  to  remember 
this  mysterious  fact  or  you'll  lop  off  your  RTS  or  BRK  or  what- 
ever is  the  highest  byte  in  your  program. 

00B00A9  00  LDA#$00 

00B02  8D  00  FF       STA  $FF00 
00B05  60  RTS 

00B06  00  BRK 

If  you  want  to  save  this  and  include  the  RTS,  you  must  S 
"FILENAME",8,0B00,OBO6,  and  if  you  wanted  to  include  that 
BRK,  you'd  need  to  specify  0B07  as  the  end  address. 

Remember,  too,  that  if  you  save  from  within  bank  1  or 
somewhere  other  than  bank  0,  that  information  is  not  trans- 
ferred to  the  disk  with  the  program.  You  must  specify  which 
bank  you  are  saving  from  if  it's  not  0,  but  when  you  go  to 
load  your  program  back  in,  it  will  load  into  bank  0  unless  you 
specify  the  bank  in  the  optional  address  field  at  the  end. 

12.  Transfer 

T  (start  address  of  source)  (end  address  of  source)  (start  address  of 
target) 

This  isn't  too  useful  since  you  can  load  to  any  target.  It 
does  not  make  your  programs  relocatable.  It  simply,  dumbly 
moves  the  zone  of  bytes  between  start  and  end  address  of 
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source  and  sets  them  down  unchanged  at  the  target.  So,  if 
you've  got  a  direct  JMP  to  some  address  within  your  ML  pro- 
gram, JMP  $B09  for  example,  the  new  version  after  the  trans- 
fer will  still  JMP  $B09  to  a  subroutine  which  is  no  longer  at 
that  location.  Also,  references  to  tables  like  error  messages  will 
be  similarly  erroneous.  It's  difficult  to  think  of  a  real  use  for 
this  function,  but  it's  there  if  you  ever  come  up  with  one. 

13.  Verify 

V  ("filename")  (,8  for  disk  or  ,1  for  tape)  ^optional  alternate  start 
address) 

This  reports  any  errors  caused  by  Save  or  it  could  be  a 
way  of  comparing  two  program  versions  for  identity.  In  prac- 
tice, because  the  Commodore  mass  storage  systems  are  so 
highly  intelligent  and  reliable,  you  may  find  you'll  never  need 
to  verify  I/O. 

14.  X  (Exit  to  BASIC) 
X 

Takes  you  out  of  the  monitor. 

15.  @  (communicate  with  disk  drive) 

@  (unit  number),  (command  string) 

You  can  see  the  directory  from  the  monitor  by  @,$  or  see 
the  disk  status  (as  with  ?DS$  in  BASIC)  by  @  with  no  com- 
mand string  at  all.  You  can  also  initialize  a  disk  with  @,I,  but 
you  should  be  in  BASIC  for  things  like  that  anyway. 

16.  $,  +,  &,  % 

These  symbols  are  put  directly  before  a  number  to  in- 
dicate whether  it  is  hex  (the  default,  so  you  don't  need  $), 
decimal,  octal  (forget  this;  you'll  probably  never  meet  anyone  \    I 

who  uses  octal,  base  8,  numbers),  and  binary.  ' — ' 

Thus,  if  you  want  to  assemble  LDA  #2  you  can  do  it  three 
useful  ways:  decimal  (LDA  #+2),  hex  (LDA  #$02),  or  binary  )    j 

which  shows  you  how  the  bits  look  in  the  byte  (LDA  4— - ' 

#%00000010).  Whichever  form  you  use,  the  128  will  convert 
the  input  to  hex  when  you  enter  the  line.  No  matter  which 
way  you  enter  the  example  instruction,  it  will  change  to  LDA 
#$02  after  you  press  RETURN. 
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P™[  Another  use  for  these  symbols  is  to  type  in  a  number  at 

-  •-  the  start  of  a  line  in  the  monitor  and  let  it  translate  the  num- 

ber into  the  four  number  bases.  If  you  want  to  know  what 
j"""7  decimal  1024  is  in  hex,  type: 

+1024 

then  press  RETURN  and  you'll  see: 

$0400 
+1024 
&2000 
o/olOOOOOOOOOO 

Conversely,  you  can  see  what  a  hex  number  would  be  in  deci- 
mal by  typing: 

$400 

or  take  a  look  at  binary.  This  can  be  useful,  particularly  when 
looking  at  someone  else's  program  or  working  with  a  map  of 
ROM  such  as  the  one  in  Appendix  C. 

Using  the  Monitor 

You  will  make  mistakes.  Monitors  are  for  checking  and  fixing 
ML  programs.  ML  is  an  exacting  programming  process,  and 
causing  bugs  is  as  unavoidable  as  mistyping  when  writing  a 
letter.  It  will  happen,  be  sure,  and  the  only  thing  for  it  is  to  go 
back  and  try  to  locate  and  fix  the  slip-up.  It  is  said  that  every 
Persian  rug  is  made  with  a  deliberate  mistake  somewhere  in 
its  pattern.  The  purpose  of  this  is  to  show  that  only  Allah  is 
perfect.  This  isn't  our  motivation  when  causing  bugs  in  an  ML 
program,  but  we'll  cause  them  nonetheless.  The  best  you  can 
do  is  try  to  get  rid  of  them  when  they  appear. 
-a.  Probably  the  most  effective  tactic,  especially  when  you  are 

/    I  just  starting  out  with  ML,  is  to  write  very  short  subroutines. 

Because  they  are  short,  you  can  more  easily  check  and  exam- 
_ ^  ine  them  to  make  sure  that  they  are  functioning  the  way  they 

should.  Let's  assume  that  you  want  to  write  an  ML  subroutine 
to  ask  a  question  on  the  screen.  (This  is  often  called  a  prompt 
since  it  prompts  the  user  to  do  something.) 

The  message  can  be  PRESS  ANY  KEY.  First,  we'll  have  to 
store  the  message  in  RAM  somewhere.  Let's  put  it  at  hex  $2000. 
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ASCII 

2000  80  P 

2001  82  R 

2002  69  E 

2003  83  S 

2004  83  S 

2005  32 

2006  65  A  \_J 

2007  78  N 

2008  89  Y 

2009  32 
200A  75  K 
200B  69  E 
200C  89  Y 
200D  00 

(The  final  zero  is  a  special  signal  to  the  computer  called  the 
delimiter  which  shows  that  the  message  is  concluded.) 

We'll  put  our  "print-it-out"  subroutine  at  address  $1F00,  a 
RAM  zone  where  BASIC  programs  usually  reside.  So,  we've 
got  the  data  at  address  $2000  and  the  subroutine  that  uses  the 
data  located  at  $1F00.  All  this  is  entirely  arbitrary.  The  ML 
programmer  can  put  things  wherever  in  RAM  he  or  she 
wishes  as  long  as  the  location  doesn't  conflict  with  other 
needs  of  the  computer  as  would  be  the  case  in  zero  page. 
Remember,  you  can  safely  put  your  ML  between  $0B00-$0BFF 
or  $1C00-$FF00  in  bank  0  and  anywhere  between  $0400- 
$FF00  in  bank  1  (or  between  $lC00-$4000  in  bank  15). 

We  haven't  gotten  into  actual  programming  yet,  but  this 
example  is  a  good  place  to  see  if  you  can  spot  an  error  in  ML 
programming.  This  subroutine  will  not  work  as  printed.  There 
are  two  errors  in  this  program.  See  if  you  can  spot  them: 

1F00    LDY   #$00        Set  up  the  Y  register  to  count  events.  \\ 

1F02    LDA  $2000,Y   Get  the  first  character  from  the  data. 

1F05    CMP  $00  Is  it  the  delimiter? 

1F07    BNE   $1F0A      If  not,  continue  on. 

1F09    RTS  It  was  zero,  so  quit  and  return  to  whatever 

JSRed,  or  called,  this  subroutine. 
1F0A  STA   $0400,Y   The  128's  text  display  area  in  40-column 

mode. 
1F0D  INY  Raise  the  counter  by  one. 

1F0E  JMP   $1F00      Always  JMP  back  to  address  $1F00. 

Since  we  haven't  yet  gone  into  addressing  or  opcodes 
much,  this  is  like  learning  to  swim  by  the  throw-them-in-the- 


42 


u 
u 

LI 


n 


/  \ 


Chapter  3 


p"*}  water  method.  Nevertheless,  see  if  you  can  make  out  how 

-    •  these  instructions  interact.  Here's  some  help:  a  BASIC  version 

of  the  same  routine,  containing  the  same  errors. 

Hf  10  DATA  P,R,E,S,S,  ,A,N,Y,  ,K,E,Y 

'-   l  20  Y  =  0 

30  READ  X:  IF  X  <>  PEEK(O)  THEN  50 
r^\  40  RETURN 

'.  .  I  50  POKE  1024  +  Y,X 

60  Y  =  Y  +  1 

70  GOTO  20 

This  subroutine  won't  work.  In  the  ML  version,  you'll  find 
two  of  the  most  common  bugs  in  ML  programming.  Unfortu- 
nately, they  are  not  obvious  bugs.  An  obvious  bug  would  be 
mistyping  LDS  when  you  meant  LDA.  Any  assembler  would 
alert  you  to  this  error  by  printing  an  error  message  to  let  you 
know  that  no  such  instruction  as  LDS  exists  in  8502  ML. 

No,  the  bugs  in  this  program  are  errors  in  logic,  in  the 
flow  or  sense  of  the  thing.  If  you  disassemble  it,  it  will  also 
look  just  fine  to  the  disassembler  program,  and  no  error  mes- 
sages will  be  printed  out  by  the  disassembler  either. 

But,  the  routine  will  not  work  the  way  you  want  it  to. 
Before  reading  on,  see  if  you  can  spot  the  two  errors.  Also,  see 
if  you  can  follow  the  events  as  the  ML  routine  runs  through  its 
loop,  picking  up  the  characters  in  the  message  and  supposedly 
depositing  them  onscreen.  Where  does  the  computer  go  after 
the  first  pass  through  the  code?  When  and  how  does  it  know 
that  it's  finished  with  its  job? 

Two  Common  Errors 

A  very  common  bug,  perhaps  the  most  common  ML  bug,  is 
r*")  caused  by  accidentally  using  zero  page  addressing  when  you 

mean  to  use  immediate  addressing.  We  mentioned  this  distinc- 
tion before,  but  it  is  the  cause  of  so  much  puzzlement  to  the 
beginning  ML  programmer  that  we're  going  to  pound  away  at 
it  several  times  in  this  book.  Zero  page  addressing  looks  very 
similar  to  immediate  addressing.  Zero  page  means  that  you  are 
dealing  with  one  of  the  cells,  or  bytes,  in  the  first  256  ad- 
dresses in  RAM  memory  in  the  computer.  The  lowest  locations 
possible. 

A  page  of  memory  is  256  bytes.  Page  1  is  from  addresses 
256  through  511  and  is  special.  It's  called  the  stack,  and  the 
computer  has  a  special  use  for  it.  We'll  get  to  it  later,  but  don't 
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try  storing  anything  in  page  1  unless  you're  fond  of  havoc.  |    i 

Addresses  512-767  comprise  page  3  which  is  the  input  buffer  lJ 

(where  a  line  is  stored  when  you  type  it  in)  for  BASIC.  The 
128  text  screen  memory  starts  at  address  $0400  (1024  in  deci-  i    t 

mal),  and  this  is  the  start  of  page  5.  And  so  on,  in  256-byte  O 

blocks,  on  up  memory  to  the  very  top,  page  255. 

In  contrast  to  zero  page  addressing  is  immediate  address-  .     , 

ing.  Immediate  addressing  means  that  the  number  you're  deal-  Li 

ing  with  is  right  within  the  ML  code  (not  somewhere  else  in 
memory).  It  means  that  you  knew  what  number  you  were 
dealing  with  and  put  it  right  into  your  program  when  you 
wrote  the  program.  Immediate  addressing  means  that  the 
number  directly  follows  an  instruction;  it's  the  argument,  the 
operand,  of  an  instruction.  LDY  #0  is  immediate  addressing.  It 
puts  the  number  0  into  the  Y  register  (see  line  1F00  in  the  ex- 
ample routine  above). 

LDY  0  is  no  t  immediate  addressing,  and  you  very  well 
might  not  get  a  zero  into  the  Y  register.  LDY  0  is  zero  page 
addressing.  LDY  34  is  also  zero  page  addressing.  Using  any 
address  lower  than  256  would  mean  zero  page  addressing. 
LDY  34  might  put  anything,  any  number,  into  the  Y  register 
because  whatever  number  is  in  address  34  will  be  placed  into 
the  Y  register.  The  key  is  that  #  symbol,  the  number  symbol. 
If  you  mean  to  load  the  number  34  into  the  Y  register,  use 
LDY  #34.  Think  of  it  as  LoaD  Y  with  number  34. 

If  you  mean  to  fetch  whatever  is  currently  in  address  34, 
use  LDY  34.  If  you  mean  hex  address  34,  use  LDY  $34.  It's 
easy  and  very  common  to  mix  up  these  two  modes — immedi- 
ate loading  which  uses  #  and  zero  page  which  has  no  symbol 
except,  perhaps,  the  $  to  identify  a  hex  number.  So,  look  for 
this  error  first  when  debugging  a  faulty  program.  Check  to  see  , 

that  all  your  zero  page  addressing  is  supposed  to  fetch  from  l^J 

RAM  and  that  all  your  immediate  mode  numbers  are  sup- 
posed to  come  from  within  the  ML  code  itself,  immediately  , 
following  the  instruction.                                                                           ^J 

In  our  example  ML  program,  LDY  #0  is  correct — we  do 
want  to  set  the  Y  register  to  zero  so  that  it  can  help  us  put  the  .     . 

characters  in  the  proper  places  on  the  screen  (STA  $0400,Y  j^J 

stores  each  character  at  address  0400,  the  screen,  plus  the  cur- 
rent value  of  Y).  For  this  purpose,  we  want  the  immediate,  the  . 
actual,  number  zero.                                                                                [_} 
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Take  a  close  look,  however,  at  the  instruction  at  location 
$1F05.  Here  we  are  trying  to  see  if  we've  picked  out  that  zero 
in  the  message  that  tells  us  the  message  is  finished.  We  want 
f*  to  CoMPare  to  the  number  zero.  But,  we  left  off  the  #  symbol 

•  -■--  that  tells  the  computer  to  use  the  number  zero.  Instead,  we're 

going  to  cause  a  comparison  against  whatever  unpredictable 
value  might  be  in  location  zero,  address  zero.  To  fix  this  bug, 
the  instruction  should  be  changed  to  read  CMP  #0  so  that  it 
will  be  immediate  mode,  not  zero  page  mode.  (If  this  confuses 
you,  take  a  look  at  line  30  in  the  BASIC  version  to  see  the 
same  flaw  in  a  familiar  context.  If  it  still  confuses  you,  don't 
worry,  we'll  be  going  over  all  this  in  much  greater  detail  in 
Chapters  4  and  6.) 

It  Never  Quits 

The  second  bug  in  this  example  routine  is  also  a  very  common 
one.  The  subroutine,  as  written,  can  never  quit;  it  will  end- 
lessly loop.  Loop  structures  are  usually  preceded  by  a  short 
setup  of  some  kind.  You  have  to  initialize  counters  before  the 
loop  can  begin  because  you  have  to  tell  it  where  to  start  and 
how  many  times  to  loop.  In  BASIC,  FOR  I  =  1  TO  10  tells  the 
computer  to  cycle  ten  times. 

In  ML,  we  set  the  Y  register  to  zero  and  let  it  act  as  our 
counter.  In  this  particular  routine,  we  don't  use  Y  to  tell  us 
when  to  stop  (that's  the  job  of  the  delimiter,  the  embedded 
zero  at  the  end  of  the  message  itself).  Instead,  Y  serves  two 
other  purposes.  It  kills  two  birds  with  one  stone.  It  is  the  off- 
set (the  pointer  to  the  current  position  in  a  list  or  series)  to 
load  the  message  in  the  data  and  is  also  the  offset  to  position 
the  letters  of  the  message  on  the  screen.  Without  Y  going  up 
one  (INY)  each  time  through  this  loop,  we  would  always  print 
the  first  letter  of  the  message  and  always  print  it  in  the  first 
position  on  the  screen. 
f^  What's  the  problem?  It's  that  JMP  instruction  at  $1F0E. 

We  should  be  jumping  back  to  address  $1F02,  but  the  JMP 
tells  us  to  jump  back  to  $1F00.  As  things  stand,  the  Y  register 
will  always  be  reset  to  zero,  there  will  never  be  a  chance  to 
read  through  the  message  and  pick  up  that  0  which  ends 
things,  and  we  cannot  therefore  ever  exit  this  loop.  We  will 
endlessly  cycle,  printing  P  over  and  over  again.  Y  will  never 
go  up  past  zero  because  each  loop  puts  a  zero  back  into  Y. 
Look  at  the  relationship  between  lines  70  and  20  in  the  BASIC 
example. 
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Tracking  Them  Down  and  Nabbing  Them 

The  monitor  will  let  you  locate  these  and  other  errors.  You  can 
replace  an  instruction  with  a  zero  (the  BReaK  command) 
which  will  stop  your  ML  program  midrun  and  let  you  see  the  \    } 

condition  of  your  variables  and  what's  going  on  in  the  reg-  ^ 

isters  at  the  breakpoint. 

If  this  doesn't  help,  you  can  get  more  specific  by  single  (    ; 

stepping  through  your  program  in  order  to  discover,  for  ex-  -— ' 

ample,  that  you  are  using  CMP  0  when  you  meant  CMP  #0. 
Unfortunately,  the  monitor  built  into  this  otherwise  excellent 
programmer's  computer  does  not  contain  one  of  the  best 
debugging  tools:  single-step  tracing.  With  this,  you  see  the  re- 
sults of  each  instruction  in  turn  as  the  computer  executes  your 
code  one  step  at  a  time.  That  can  be  a  real  shortcut  to  locating 
errant  programming.  Monitor  add-ons  for  all  the  previous 
Commodore  computers  have  included  single-step  functions 
and,  doubtless,  one  will  be  published  in  COMPUTE!  magazine 
or  COMPUTERS  Gazette  soon.  But,  as  of  this  writing,  no  such 
tool  is  yet  available. 

It  would  also  be  easy,  by  stepping,  to  notice  that  your  Y 
register  is  being  reset  to  zero  every  time  through  the  loop.  For 
single  stepping,  it's  good  to  first  make  a  printout  of  the  sus- 
pect area  of  your  program  so  that  you  can  follow  along  during 
the  single  stepping.  If  the  Y  register  keeps  turning  back  into 
zero,  that  clues  you  that  this  register  isn't  cooperating;  it's  not 
counting  up  each  time  through  the  loop  the  way  you  intended 
it  to.  These  and  other  errors,  if  not  always  immediately  ob- 
vious, are  at  least  discoverable  from  within  the  monitor. 

Also,  the  disassembler  function  of  the  monitor  will  permit 
you  to  study  the  program  and  look,  deliberately,  for  the  cor- 
rect use  of  #00  and  $00.  Since  that  mixup  between  immediate 
and  zero  page  addressing  is  so  common  an  error,  always  check 
for  it  first. 

Programming  Tools  O 

The  single  most  significant  quality  of  monitors  which  contrib- 
utes to  easing  the  ML  programmer's  job  is  that  monitors,  like 
BASIC,  are  interactive.  This  means  that  you  can  make  changes 
and  test  them  right  away,  right  then.  In  BASIC,  you  can  find 
an  error  in  line  120,  make  the  correction,  and  run  a  test  im- 
mediately. You  can  insert  a  STOP  in  BASIC  or  a  BRK  in  ML 
and  look  at  your  variables  and  registers. 

46  U 


U 


U 

Li 


n 


i  \ 


Chapter  3 


j   i 


f*-i  It's  not  always  that  easy  to  locate  and  fix  bugs  in  ML: 

L  »  There  are  few  error  messages  which  point  out  faulty  program 

logic,  so  finding  the  location  of  a  logic  bug  can  be  difficult. 
j— |  But  a  monitor  does  allow  interactivity:  You  make  changes 

I  ,„i  and  test  them  on  the  spot.  This  is  one  of  the  drawbacks  of 

complex  assemblers,  especially  those  which  have  several  steps 
between  the  writing  of  the  source  code  and  the  final  assembly 
of  executable  object  code  (ML  which  can  be  executed).  LADS, 
however,  was  designed  to  maximize  interactivity,  and  you 
should  find  that  its  speed  of  assembly,  its  open  architecture 
(you  can  easily  modify  it,  adding  your  own  error  messages  and 
bug  traps),  and  its  BASIC -like  environment  will  all  contribute 
to  quick  program  adjustments  and  quick  testing. 

Unfortunately,  other  sophisticated  assemblers  often  re- 
quire several  steps  between  writing  an  ML  program  and  being 
able  to  test  it.  These  assemblers  can  require  linkers,  relocatable 
loaders,  mapping,  global/local  variable  definition,  macros, 
separate  and  clumsy  source  code  editors,  and  other  "features" 
which  contribute  little  to  the  actual  assembly  of  a  program  or 
to  the  comfort  of  the  programmer.  If  you  don't  already  know 
the  function  of  these  "enhancements,"  count  it  a  blessing. 
They  greatly  retard  program  development  except  in  pro- 
fessional, programming-by-committee  situations.  These  func- 
tions make  it  easier  to  rearrange  ML  subroutines,  put  them 
anywhere  in  memory  without  modification,  and  so  forth.  They 
make  ML  greatly  modular  (composed  of  very  small,  self-suf- 
ficient modules  or  subroutines),  but  they  also  make  it  far  less 
interactive.  You  cannot  easily  make  a  change  and  see  the  ef- 
fects at  once. 

One  obvious  reason  for  this  kind  of  assembler,  for  it  hav- 
p_  ing  value  at  all,  is  that  you  want  to  discourage  interactivity 

L_l  when  five  people  are  writing  separate  sections  of  the  same 

program.  In  that  environment,  all  programmers  must  play  by 
j— ^  the  same  rules  and  things  like  macros  and  relocatability  have 

I   j  value.  For  the  individual  programmer,  however,  restrictions 

like  these  can  prove,  in  the  long  run,  more  of  a  hindrance  than 
__  a  help.  Industrial-strength  linker/assemblers  are,  for  the  in- 

i    i  dividual  programmer,  rather  like  installing  pay  toilet  stalls  in 

your  bathroom.  For  most  people,  it's  not  merely  unnecessary, 
_  it's  downright  inconvenient. 

)_J,  However,  using  the  monitor's  mini-assembler,  or  LADS 

from  this  book,  you  are  right  near  the  monitor  level,  and  fixes 
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can  be  easily  and  quickly  tested.  In  other  words,  the  assem- 
blers which  are  best  for  individual  programmers  trade  ef- 
ficiency for  group-programming  communication  requirements. 
Personal  assemblers,  like  personal  computers,  should  reflect  ,    j 

the  needs  of  the  programmer,  not  the  needs  of  industrial,  l*J 

programming  teams.  Personal  assemblers  should  involve  little, 
if  any,  preplanning,  less  forethought,  less  abstract  analysis, 
and  no  rules  for  communicating  between  one  programmer  and 
another.  If  something  goes  awry,  you  can  just  try  something 
else  until  it  all  works.  Not  only  does  this  help  you  learn,  it's 
also  significantly  the  fastest  way  to  program. 


U 


Plan  Ahead  or  Plunge  In? 

Some  people  find  such  trial-and-error  programming  un- 
comfortable, disgraceful  even.  Industrial  assemblers  (and  some 
assemblers  currently  sold  for  personal  use)  discourage 
interactivity,  requiring  flowcharts,  even  expecting  the  pro- 
grammer to  write  out  a  program  ahead  of  time  on  paper  and 
debug  it  before  even  sitting  down  at  the  computer. 

In  one  sense,  these  large  assemblers  are  a  holdover  from 
the  early  years  of  computing,  when  computer  time  was  ex- 
tremely expensive. 

There  was  a  clear  advantage  to  coming  to  the  terminal  as 
prepared  as  possible.  Interactivity  was  costly.  But,  like  the 
increasingly  outdated  advice  urging  programmers  to  worry 
about  saving  computer  memory  space,  it  seems  that  strategies 
designed  to  conserve  computer  time  are  also  anachronistic. 
You  can  spend  all  the  time  you  want  on  your  personal 
computer. 

Complex  assemblers  tend  to  downgrade  the  importance  of 
a  monitor,  to  reduce  its  function  in  the  programming  process. 
Some  programmers  who've  worked  on  large  IBM  mainframe  l^J 

computers  for  20  years  do  not  know  what  the  word  monitor 
means  in  the  sense  we  are  using  it. 

To  them,  monitors  are  CRT  screens.  The  machine  Ian-                   ^J 
guage  tools  used  for  years  by  mainframe  programmers  often 
have  what  we  call  a  monitor,  but  it  will  be  seriously  restric- 
tive. It  can,  for  example,  have  no  provision  for  saving  an  ML  j | 

program  to  disk  or  tape  from  within  the  monitor. 

Whether  or  not  you  prefer  the  interactive  style  of  personal 
programming,  its  greater  reliance  on  the  monitor  and  on  trial-  )    I 

and-error  programming,  is  your  decision.  If  you're  used  to 
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group  programming,  you  might  find  it  difficult  to  abandon  the 
preplanning,  the  flowcharts,  and  all  the  rest.  The  choice  is  ul- 
timately a  matter  of  personal  style. 


L  _j         Time  Is  Cheap 

Some  programmers  are  uncomfortable  unless  they  have  a 
r— i  fairly  complete  plan  before  they  even  get  to  the  computer  key- 

>'_]  board.  Others  are  quickly  bored  by  elaborate  flowcharting, 

"dry  computing"  on  paper,  and  can't  wait  to  get  on  the  com- 
puter and  see-what-happens-if. 

Perhaps  a  good  analogy  can  be  found  in  the  various  ways 
that  people  make  telephone  calls.  When  long-distance  calls 
were  extremely  expensive,  most  people  made  lists  of  what 
they  wanted  to  say  and  carefully  planned  the  call  before  dial- 
ing. They  would  also  watch  the  clock  during  the  call.  (Some 
still  do  this  today.)  As  the  costs  of  phoning  came  down,  many 
people  found  that  spontaneous  conversation  was  more  satisfy- 
ing. It's  up  to  you. 

Computer  time,  though,  is  now  extremely  cheap.  If  your 
computer  uses  100  watts  and  your  electric  company  charges  5 
cents  per  kilowatt-hour,  never  turning  your  machine  off  would 
only  cost  about  12  cents  a  day. 
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Addressing 


'     '  The  8502  processor  is  an  electronic  brain.  It  performs  a  variety 

of  manipulations  with  numbers  to  allow  us  to  write  words,  draw 
(—1  pictures,  control  outside  machines  such  as  recorders  and  disk 

-1  drives,  calculate,  and  do  many  other  things.  It  was  designed  to 

be  logical  and  fast,  to  work  accurately  and  efficiently. 

If  you  could  peer  down  into  the  CPU  (Central  Processing 
Unit),  the  heart  of  the  processor,  you  would  see  numbers  be- 
ing delivered  and  received  from  memory  locations  all  over  the 
computer.  Sometimes  the  numbers  arrive  and  are  sent  out,  un- 
changed, to  some  other  address.  Other  times  they  are  com- 
pared, added,  or  otherwise  modified,  before  being  sent  back  to 
RAM  or  to  a  peripheral. 

Writing  an  ML  program  can  be  compared  with  planning 
the  activities  of  this  message  center.  This  can  be  illustrated  by 
thinking  of  computer  memory  as  a  City  of  Bytes  with  the  CPU 
acting  as  the  main  post  office  (Figure  4-1).  The  CPU  uses  four 
tools  to  do  its  job:  three  registers,  a  program  counter,  a  stack 
pointer,  and  seven  little  one-bit  flags. 

The  monitor,  if  you  type  R  (for  registers),  will  display  the 
present  status  of  these  tools.  It  looks  something  like  this: 

PC     SR   AC  XR  YR  SP 

;FB000    30     01     00     FF    F8 

A,  X,  and  Y  are  the  registers,  SR  is  the  processor  status  flags 
(each  bit  in  this  byte  is  a  flag),  PC  is  the  program  counter  (the 
address  of  the  last  instruction  executed  plus  two  before  we  en- 
tered monitor  mode),  and  SP  is  the  stack  pointer.  You  can 

r^j  more  or  less  let  the  computer  handle  the  stack  pointer.  It 

keeps  track  of  numbers,  usually  return-from-subroutine  ad- 
dresses, which  are  kept  together  in  a  list  called  the  stack. 

J"~j  The  computer  will  automatically  manipulate  the  stack 

pointer.  It  will  also  handle  the  program  counter  (PC)  which 
keeps  track  of  where  you  are  located  at  any  given  time  within 
the  computer.  For  example,  each  ML  instruction  can  be  either 
one,  two,  or  three  bytes  long.  TYA  has  no  argument  and  is  the 
instruction  to  transfer  a  number  from  the  Y  register  to  the 

r~\  accumulator.  Since  it  has  no  argument,  the  PC  can  locate  the 

next  instruction  to  be  carried  out  by  adding  one  to  itself.  If  the 
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PC  held  $4000,  it  would  hold  $4001  after  execution  of  a  TYA. 
Whenever  you  insert  a  BRK  instruction,  you  cause  the  pro- 
gram to  halt  at  that  point  and  enter  monitor  mode.  The  PC 

r-s  shows  you  where,  in  your  program,  you  halted. 

I    (  LDA  #$01  is  a  two-byte  instruction.  It  takes  up  two  bytes 

in  memory,  so  the  next  instruction  to  be  executed  after  LDA 

^-i  #$01  will  be  two  bytes  beyond  it.  In  this  case,  the  PC  will 

1  J  raise  itself  from  $4000  to  $4002.  But  we  can  just  let  it  work 

merrily  away  without  worrying  about  it  other  than  to  note  the 
location  when  setting  several  BRKs  in  a  program  to  debug  it. 

The  Accumulator:  The  Busiest  Register 

SR,  A,  X,  and  Y,  however,  are  our  business.  They  are  all  eight 
bits,  or  one  byte,  in  size.  They  are  not  located  in  memory 
proper.  You  can't  PEEK  them  since  they  have  no  address  like 
the  rest  of  memory.  They  are  zones  of  the  CPU.  The  A  reg- 
ister, most  often  called  the  accumulator,  is  the  busiest  place  in 
the  computer.  The  great  bulk  of  the  mail  comes  to  rest  here,  if 
only  briefly,  before  being  sent  to  another  destination. 

Any  logical  transformations  (EOR,  AND,  ORA)  or 
arithmetic  operations  leave  their  results  in  the  accumulator. 
Most  of  the  bytes  streaming  through  the  computer  come 
through  the  accumulator.  You  can  compare  one  byte  against 
another  using  the  accumulator.  And  nearly  everything  that 
happens  which  involves  the  accumulator  will  have  an  effect 
on  the  status  register  (SR,  the  flags).  We  won't  need  to  actually 
work  directly  with  the  status  register,  but  the  information  it 
holds  will  be  significant  because  several  important  instruc- 
tions, like  Branch  if  EQual  (BEQ)  test  to  see  if  a  flag  is  up  or 
down  when  deciding  where  to  send  the  program  for  the  next 
,_ .  task.  BEQ  looks  at  the  SR  and  checks  whether  or  not  the  Z 

■     \  flag  (zero  was  the  result  of  the  most  recent  event)  is  up. 

The  X  and  Y  registers  are  similar  to  each  other  in  that  one 
f-^  of  their  main  purposes  is  to  assist  the  accumulator.  They  are 

used  as  addressing  indexes.  There  are  some  methods  of 
addressing  that  we'll  get  to  in  a  minute  which  add  an  index 
value  to  another  number.  For  example,  if  the  X  register  is  cur- 
rently holding  a  five,  LDA  $4000,X  will  load  the  byte  in  ad- 
dress $4005  into  A.  In  other  words,  the  real  address  when 
you're  using  indexed  addressing  is  the  number  plus  the  index 
value.  If  X  has  a  six,  then  we  load  from  $4006.  Why  not  just 
LDA  $4006?  The  reason  is  that  it's  far  easier  to  raise  or  lower 
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an  index  inside  a  loop  structure  than  it  would  be  to  write  in  , 

each  specific  address  literally.  I | 

A  second  major  use  of  X  and  Y  is  in  counting  and  loop- 
ing. We'll  go  into  this  more  in  the  chapter  on  the  instruction  . 
set.  We'll  also  have  some  things  to  learn  later  about  SR,  the                 o_! 
status  register,  which  holds  some  flags  showing  current  con- 
ditions. Among  other  things,  the  SR  can  tell  a  program  or  the 
CPU  if  there  has  been  a  zero,  a  carry,  or  a  negative  number  as 
the  result  of  some  operation.  Although  it's  not  important  to  be 
able  to  work  directly  with  the  status  register,  knowing  about 
carry  and  zero  flags  is  especially  significant  in  ML.  The 
branching  instructions  will  check  these  flags  for  you,  but  you 
should  be  aware  of  what  some  of  the  flags  signify. 

But  we  can  leave  learning  about  the  instructions  until  we 
get  to  Chapter  6.  For  now,  the  task  at  hand  is  to  explore  the 
various  "classes"  of  mail  delivery,  the  8502  addressing  modes. 

The  computer  must  have  a  logical  way  to  pick  up  and 
send  information.  Rather  like  a  postal  service  in  a  dream — 
everything  should  be  picked  up  and  delivered  rapidly,  and 
nothing  should  be  lost,  damaged,  or  delivered  to  the  wrong 
address. 

The  8502  accomplishes  its  important  function  of  getting 
and  sending  bytes  (GET  and  PRINT  would  be  examples  of  the 
same  activity  in  BASIC)  by  using  several  addressing  modes. 
There  are  13  different  ways  that  a  byte  might  be  "mailed" 
either  to  or  from  the  central  processor. 

When  programming,  in  addition  to  picking  an  instruction 
(of  the  56  available  to  you)  to  accomplish  the  job  you  are 
working  on,  you  must  also  make  one  other  decision.  You  must 
decide  how  you  want  to  address  the  instruction — how,  in  other 
words,  you  want  the  mail  sent  or  delivered.  There  is  some 
room  for  maneuvering,  however.  It  will  rarely  matter  if  you 
should  choose  a  slower  delivery  method  than  you  could  have. 
Nevertheless,  it  is  worth  knowing  about  the  various  address- 
ing modes;  most  of  them  are  designed  to  be  helpful  during 
some  particular  programming  activity. 


u 


Absolute  and  Zero 

Let's  picture  a  postman's  dream  city,  a  city  so  well  planned 
from  a  postal-delivery  point  of  view  that  no  byte  is  ever  lost, 

damaged,  or  sent  to  the  wrong  address.  It's  the  City  of  Bytes  j I 

we  first  toured  in  Chapter  2.  It  has  65536  houses  all  lined  up 
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on  one  side  of  a  street  (a  long  street).  Each  house  is  clearly  la- 
beled with  its  number,  starting  with  house  0  and  ending  with 
house  65535.  When  you  want  to  get  a  byte  from  or  send  a 
byte  to  a  house  (each  house  holds  one  byte),  you  must  "ad- 
dress" the  package  (See  Figure  4-2). 

Let's  look  at  the  most  elementary  mode  of  addressing.  It's 
quite  popular  and  could  be  thought  of  as  "first  class."  Called 
absolute  addressing,  it  can  send  a  number  to  or  receive  one 
from  any  house  in  the  city.  It's  what  we  normally  think  of  first 
when  the  idea  of  addressing  something  comes  up.  You  just  put 
the  number  on  the  package  and  send  it  off.  No  indexing  or 
special  instructions.  If  it  says  2500,  then  it  means  house  2500. 

1000  STA  $2500 

or 

1000  LDA  $2500 

These  two,  STore  A  and  LoaD  A,  STA  and  LDA,  are  the 
instructions  which  get  a  byte  from  or  send  it  to  the  accu- 
mulator. The  address,  though,  is  those  numbers  following  the 
instruction.  The  item  following  an  instruction  is  sometimes 
called  the  instruction's  argument.  You  could  have  written  the 
above  addresses  several  ways.  Writing  $2500,  however,  tells 
the  computer  to  carry  out  the  instruction  with  respect  to  ad- 
dress $2500,  to  store  or  load  the  byte  from  that  location.  This 
kind  of  addressing  uses  just  a  simple  $  (to  show  that  this  is  a 
hex,  not  decimal,  number)  and  a  four-digit  number.  You  can 
send  the  byte  in  the  accumulator  to  anywhere  in  normal  64K 
memory  by  this  method  (or  retrieve  it  from  anywhere). 
Remember,  too,  that  if  you  send  a  byte  from  the  accumulator, 
it  also  remains  in  the  accumulator.  It's  more  a  copying  than  a 
literal  sending.  Getting  and  sending  to  the  128's  alternative 
RAM  banks  is  another  matter;  it  will  be  covered  below.  i ! 

Heavy  Traffic  in  Zero  Page  u   . 

A  second  addressing  mode,  called  zero  page,  we've  touched  on  L.J 

before.  If  you  are  sending  a  byte  down  to  anywhere  between 

addresses  0  and  255  ($0000  and  $00FF),  the  zero  page,  you  can  ,     . 

just  leave  off  the  first  two  numbers:  1000  STA  $07.  (Remem-  l ! 

ber  that  the  1000  is  the  address,  the  location,  of  the  instruc- 
tion, not  the  argument,  or  target,  of  the  instruction.)  (     , 

Zero  page  addressing,  using  only  two  hex  digits  or  deci-  1 | 

mal  numbers  lower  than  256,  is  pretty  fast  mail  service:  The 
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[""!  mail  carrier  has  to  worry  about  choosing  between  only  256  in- 

stead of  65536  possible  houses.  And,  also,  the  computer  is 
specially  wired  to  service  these  special  addresses.  Think  of 
["""[  them  being  close  to  the  post  office.  Things  get  picked  up  and 

delivered  rapidly  in  zero  page.  That's  precisely  why  your 
BASIC  and  operating  systems  tend  to  use  it  so  often. 
]~1  Although  zero  page  addressing  works  only  with  the  first 

256  locations  in  your  computer,  it  gets  more  than  its  share  of 
the  mail.  The  128's  BASIC  language,  its  operating  system,  and 
disk  operating  systems  use  up  most  of  zero  page  to  hold  flags 
and  other  temporary  information  they  need.  Why?  Because 
zero  page  addressing  is  the  fastest  of  all  the  addressing  modes. 
It's  nearly  instantaneous.  Since  the  128  has  appropriated  these 
first  256  houses  for  its  own  use,  there's  not  much  room  left 
over  down  there  for  you  to  store  your  own  ML  pointers  or 
flags,  not  to  mention  entire  subroutines.  You  will,  however, 
want  to  squeeze  in  some  address  pointers,  which  we'll  get  to 
in  a  minute.  After  all,  your  programs,  too,  will  sometimes 
want  the  fastest  possible  service. 

These  two  addressing  modes,  absolute  and  zero  page,  are 
very  common  ones.  In  your  programming,  however,  you  prob- 
ably won't  get  to  use  zero  page  as  much  as  you  might  want 
to.  You  will  notice  on  a  map  of  the  128  that  zero  page  is 
heavily  trafficked.  You  could  cause  a  problem  by  storing 
things  in  zero  page  where  the  128  expects  to  use  it  for  its  own 
purposes.  You  can  find  a  map  of  the  128  in  Appendix  C.  Maps 
not  only  tell  you  what  space  must  be  avoided,  but  also  where 
to  access  the  many  built-in  BASIC  routines  in  your  computer. 
More  about  this  later. 

There  are,  however,  safe  areas  for  you  to  use  down  there 
j— -j  in  those  exclusive  locations  in  lower  RAM  memory.  The  buffer 

'     '  for  the  cassette  recorder  ($B00)  or  for  BASIC  activities  like 

floating-point  arithmetic  are  safe  when  you're  not  using  a  tape 
r"l  drive  or  BASIC.  So,  if  you  put  your  pointers  and  flags  into 

1    '  these  addresses,  things  will  be  fine.  In  any  case,  zero  page  is  a 

popular,  busy  neighborhood.  Don't  put  any  of  your  actual  ML 
programs  there.  Your  main  use  of  zero  page  will  be  to  hold 
pointers  for  an  especially  useful  addressing  mode  called  in- 
direct Y  that  we're  going  to  look  at  in  detail.  But  you've  al- 
ways got  to  make  sure  that  you  aren't  interfering  with  the 
128  s  own  requirements  for  space  in  zero  page.  If  BASIC  is  ac- 
tive, you  can  only  be  sure  of  the  safety  of  addresses  $FA-$FE. 
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However,  if  your  ML  routine  isn't  accessing  I/O  routines  at  I     j 

the  time,  you  can  use  cassette-specific  zero  page  areas.  If  it's 
not  using  floating  point,  you  can  use  the  accumulators.  Some- 
times, it's  easiest  just  to  try  using  some  addresses  in  zero  page  J    I 
and  see  if  your  program  runs  correctly. 

While  we're  on  the  subject  of  places  to  avoid,  keep  out  of 
page  1  (decimal  addresses  256-511),  too.  That's  for  the  stack,  {    ! 

about  which  more  later.  We'll  get  to  the  safe  places  in  RAM  — f 

that  you  can  use  for  your  ML  programs  and  their  flags,  vari- 
ables, tables,  and  so  on.  It's  always  okay  to  use  ordinary 
higher  RAM  as  long  as  you  keep  BASIC  programs  from 
putting  their  variables  on  top  of  the  ML  and  keep  the  ML 
from  writing  over  BASIC  (if  you  want  them  to  coexist  during  a 
program  run).  And,  using  the  special  addressing  techniques 
and  bank  switching  we'll  discuss  below,  you  can  access  the 
entire  64K  of  bank  1  which  is  all  blank  RAM. 

The  safest  place  of  all  for  short  ML  routines  is  between 
addresses  2816  ($B00)  and  3071  ($BFF)  since  the  128  leaves 
these  RAM  locations  essentially  undisturbed  unless  the  cas- 
sette drive  is  active.  So,  when  you  want  to  practice  with  the 
examples  in  this  book,  it's  always  okay  to  give  the  LADS 
assembler  a  start  address  instruction  of  *=  $B00  or  its  decimal 
equivalent  *=  2816. 

Immediate 

Another  very  common  addressing  mode  is  called  immediate 
addressing — it  deals  directly  with  a  number.  Instead  of  send- 
ing away  for  the  number,  we  can  just  shove  it  directly  into  the 
accumulator  by  putting  the  number  right  in  the  same  place 
where  the  other  addressing  modes  would  have  an  address. 
Let's  illustrate  this:  v    I 

BOO  LDA  $2500  Absolute  mode,  loading  from  address  2500  — ' 

BOO  LDA  #$9      Immediate  mode,  put  number  9  into  the 

accumulator  i     t 

The  first  example  will  load  the  accumulator  with  whatever 

number  is  found  in  address  $2500.  In  the  second  example,  we  ,    , 

simply  wanted  to  put  a  $9  into  the  accumulator.  We  know  I I 

that  we  want  the  number  $9.  So,  instead  of  sending  off  for  the 

$9,  we  just  type  in  a  $9  where  we  normally  would  put  a  ,    , 

memory  address.  And  we  tack  on  the  #  symbol  to  show  that  i I 

the  $9  is  the  number  we're  after.  Without  that  #,  the  computer 
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would  load  the  accumulator  with  whatever  it  finds  at  address 
$9  (as  in  LDA  $9).  Without  the  #,  it  would  be  zero  page 
addressing,  not  immediate  addressing. 

|~"|  In  any  case,  immediate  addressing  is  very  commonly 

used,  since  you  often  know  already  what  number  you  are  after 
and  do  not  need  to  send  away  for  it  at  all.  One  example 

j— 1  would  be  printing  out  a  carriage  return  on  the  screen.  You  al- 

ready know  that  the  code  for  a  carriage  return  is  13,  so  you 
just  load  it  into  the  accumulator  with  LDA  #13.  This  is  similar 
to  BASIC  where  you  define  a  variable  (10  VARIABLE  -  9).  In 
this  case,  we  have  a  variable  being  given  a  known  value.  LDA 
#9  is  the  same  idea.  (When  using  the  mini-assembler  in  128's 
built-in  monitor,  remember  that  it  assumes  numbers  are  hex 
unless  otherwise  indicated.  For  the  LADS  assembler  from  this 
book,  LDA  #10  means  "put  the  value  10  into  the  accu- 
mulator," but  the  same  instruction  to  the  mini-assembler  will 
put  the  decimal  value  16  (hex  $10)  in  the  accumulator.  To  use 
decimal  numbers  you  must  always  add  a  +  sign:  LDA  #  +  10.) 

To  repeat,  immediate  addressing  is  used  when  you  know 
what  number  you're  dealing  with;  you're  not  sending  off  for 
it.  It's  put  right  into  the  ML  program  code  as  a  number,  not  as 
an  address.  To  illustrate  immediate  and  absolute  addressing 
working  together,  imagine  that  you  wanted  to  copy  the  num- 
ber 15  ($0F)  into  address  $4000  (see  Program  4-1). 

Implied 

Here's  an  easy  one.  You  don't  use  any  address  or  argument 
with  this  one.  You  just  type  the  instruction;  it  sits  alone,  needs 
no  argument. 

This  is  probably  the  easiest  addressing  mode  to  grasp.  It's 
called  implied,  since  the  mnemonic,  the  instruction  itself,  im- 
plies what  is  being  sent  where:  TXA  means  Transfer  the  X  reg- 
ister's contents  to  the  Accumulator.  Implied  addressing  means 
that  you  do  not  type  anything  following  the  instruction.  The 
instruction  defines  what's  being  done  without  your  having  to 
give  it  any  argument. 

TYA  and  others  are  similar  short-haul  moves  from  one 

register  to  another.  Included  in  this  implied  group  are  the 

SEC,  CLC,  SED,  CLD  instructions  as  well.  They  merely  clear 

or  set  the  flags  in  the  status  register,  thereby  letting  you  and 

the  computer  keep  track  of  whether  or  not  the  most  recent 

arithmetic  resulted  in  a  zero,  whether  or  not  a  carry  occurred, 

and  so  forth. 
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Also  "implied"  are  such  instructions  as  RTS  (ReTurn  from 
Subroutine),  BRK  (BReaK,  which  is  the  ML  equivalent  of  BA- 
SIC'S STOP  command),  PLP,  PHP,  PLA,  PHA  (which  "push" 
or  "pull"  the  processor  status  register  or  accumulator  onto  or 
off  the  stack). 

Increasing  by  one  (incrementing)  the  X  or  Y  register's 
r-»  number  (INX,  INY)  or  decreasing  it  (DEX,  DEY)  are  also  "im- 

'  plied."  What  all  of  these  implied  addressing  modes  have  in 

common  is  the  fact  that  you  do  not  need  to  actually  give  any 
address.  By  comparison,  an  LDA  $2500  (the  absolute  mode) 
must  have  that  $2500  address  to  know  where  to  pick  up  the 
package.  TXA  already  says,  in  the  instruction  itself,  that  the 
address,  the  destination,  is  the  accumulator.  Likewise,  you  do 
not  put  an  address  after  RTS  since  the  computer  always 
memorizes  its  jump-off  address  when  it  does  a  JSR.  NOP  (NO 
oPeration)  is,  of  course,  implied  mode,  too. 

Relative 

One  particular  addressing  mode,  the  relative  mode,  used  to  be 
a  real  headache  for  programmers.  Not  so  long  ago,  in  the  days 
when  ML  programming  was  done  "by  hand,"  this  was  a  fre- 
quent source  of  errors.  Hand  computing — entering  each  byte 
by  flipping  eight  switches  up  or  down  and  then  pressing  an 
ENTER  key — meant  that  the  programmer  had  to  first  write  a 
program  on  paper,  translate  the  mnemonics  into  their  number 
equivalents,  and  then  "key"  the  whole  thing  into  the  machine 
with  that  set  of  switches. 

It  was  a  big  advance  when  hexadecimal  numbers  permit- 
ted entering  $0F  instead  of  eight  switches:  00001111.  This  re- 
duced errors  and  fatigue. 
i— I  An  even  greater  advance  was  having  enough  free  memory 

<     i  so  that  an  assembler  program  could  be  in  the  computer  while 

the  ML  program  was  being  written.  An  assembler  not  only 
takes  care  of  translating  LDA  $2500  into  its  three  (eight- 
switch)  numbers — 10101101  (the  code  for  the  instruction 
LDA)  and  00000000  00100101  (the  number  $2500)^but  an 
assembler  also  does  relative  addressing.  So,  for  the  same  rea- 
son that  you  can  program  in  ML  without  knowing  how  to  deal 
with  binary  numbers,  you  can  also  forget  about  relative 
addressing.  The  assembler  will  do  it  for  you.  All  you  need  to 
remember  about  it  is  that  you  can't  go  very  far  away  from  the 
current  instruction  when  using  relative  addressing  and  LADS 
will  warn  you  if  you  try. 
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Relative  addressing  is  used  with  eight  instructions  only: 
BCC  BCS,  BEQ,  BMI,  BNE,  BPL,  BVC,  BVS.  They  are  all 
branching  instructions.  They  force  the  control  of  the  program 
to  branch  (jump)  when  the  overflow  flag  is  set  (or  cleared); 
when  the  carry  flag  is  set  (or  cleared);  or  if  the  most  recent  ' — ' 

arithmetic  resulted  in  equal,  less  than,  not  equal,  or  more  than. 

Branch  if  EQual  (BEQ)  would  look  like  this  in  BASIC:  IF  X 
=  0  THEN  GOTO.  It  forces  the  computer  to  branch  some- 
where else  in  a  program  if  something  is  equal  to  zero. 

All  these  B  instructions  can  branch  only  as  far  as  128  ad- 
dresses forward  or  127  backward  from  where  the  instruction  is 
located.  If  you  were  delivering  the  mail  in  the  City  of  Bytes, 
you  would  probably  dislike  relative  addresses;  it  would  mean 
extra  work.  You  would  be  going  peacefully  from  house  to 
house  up  the  road  and  then,  suddenly,  one  of  the  letters  has  a 
giant  B  on  it  and  a  number  like  —5  or  +47.  You've  then  got 
to  stop  your  orderly  progress  up  the  road  and  take  this  letter  5 
houses  back  from  the  current  house  or  47  houses  forward. 

Remember  that  these  branches,  these  jumps,  can  be  a  dis- 
tance of  only  128  bytes  from  their  own  addresses,  but  they 
can  go  in  either  direction.  Thus,  if  a  BNE  instruction  above  is 
located  in  RAM  at  address  $3500,  you  cannot  specify  $5600  as 
its  target.  That  would  be  much  too  big  a  branch.  However,  if 
you  do  exceed  the  limit  of  branching,  LADS  will  print  "Branch 
Out  Of  Range"  and  give  you  the  line  number  where  the  error 
was  so  that  you  can  easily  correct  it. 

When  using  the  B  instructions  to  branch  relatively,  you 
specify  where  the  branch  should  go  by  giving  an  address 
within  the  boundaries  of  128  bytes  in  either  direction.  Here's 
an  example: 

1000  LDX  #$00 

1002  INX 

1003  BNE  $1002 
1005  BRK 

(The  X  register  in  this  example  will  count  up  by  ones  until 
it  hits  255  decimal.  At  that  point,  it  resets  itself  to  zero.  When 
it  does  become  zero,  that  will  fail  to  trigger  the  Branch  if  Not 
Equal  to  zero  instruction,  and  we  will  "fall  through"  the 
branch  to  the  BRK  at  $1005.) 

This  is  how  you  create  an  ML  FOR-NEXT  loop.  You  are 
branching  relative  to  address  1003,  which  means  that  the 


64 


n 


Chapter  4 


I"!  assembler  will  calculate  what  address  to  place  into  the  com- 

puter that  will  get  you  to  address  $1002.  You  might  wonder 
what's  wrong  with  the  computer  just  accepting  the  number 

i~~|  $1002  as  the  address  to  which  you  want  to  branch.  Absolute 

addressing  does  give  the  computer  the  actual  address,  but  the 
branching  instructions  all  need  addresses  which  are  offsets  of 

p~j  the  starting  address.  After  assembling  the  example  above,  the 

assembler  puts  the  following  into  the  computer: 

1000  A2  00 

1002  E8 

1003  DO  FD 
1005  00 

The  odd  thing  about  this  piece  of  code  is  the  FD  which 
LADS  will  assemble  into  address  $1004.  How  does  $FD  tell 
the  computer  to  branch  back  to  $1002?  $FD  is  253  decimal. 
Now  it  begins  to  be  clear  why  relative  addressing  used  to  be 
so  messy  to  program.  If  you  are  curious,  numbers  larger  than 
127,  when  used  as  arguments  for  the  B  instructions,  tell  the 
computer  to  go  back  down  to  lower  addresses.  What's  worse, 
the  larger  the  number,  the  less  far  down  it  goes.  In  this  case, 
the  computer  counts  the  address  $1005  as  zero  and  counts 
backward  thus: 

1005  =      0  =  $00 

1004  =  255  =  $FF 
1003  =  254  =  $FE 
1002  =  253  =  $FD 

Not  a  very  pretty  counting  method.  It's  easy  for  the  com- 
puter to  deal  with  this,  but  to  us  it's  awkward  and  strange. 
Fortunately,  all  that  we  LADS  assembler  users  need  do  is  to 
assign  a  label  to  the  address  we're  branching  to  and  use  the 
|  label  as  the  address  (as  if  it  were  an  absolute  address).  The 

assembler  will  do  the  hard  part.  So,  relative  branching  be- 
comes quite  easy  when  using  LADS  because  you  label  ad- 
dresses and,  thus,  don't  need  to  know  the  particular  address  to 
give  as  the  argument  of  the  B  instructions  (or  JSR  or  JMP 
either).  (However,  if  you're  using  the  simple  assembler  in  the 
128's  monitor,  you  will  need  to  specify  an  address;  there  are 
no  labels  permitted  in  the  monitor.) 

The  strange  counting  method  illustrated  by  relative 
addressing  is  the  way  that  the  computer  handles  negative 
numbers.  It  thinks  of  the  leftmost  bit  in  a  byte  as  the  sign  bit. 
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Whether  the  bit  is  on  or  off  signifies  a  positive  or  negative  j     I 

number.  For  the  beginning  ML  programmer,  however,  it's  just  '—-' 

as  well  to  forget  all  about  negative  numbers.  You  won't  find 
that  you'll  need  to  use  them  since  practically  everything  you'll  |    | 

want  to  do  can  be  done  with  positive  integers. 

Before  leaving  our  discussion  of  branching,  let's  look  at 
one  special  problem  that  you  will  need  to  deal  with  if  you  use  \    i 

the  simple  assembler  in  the  monitor.  When  you  are  using  one  ' — ' 

of  the  branch  instructions,  you  sometimes  branch  forward.  Let's 
say  that  you  want  to  have  a  different  kind  of  FOR-NEXT  loop: 

1000  LDX  #$0 

1002  INX 

1003  BEQ  $100A 
1005  JMP  $1002 

1008  BRK 

1009  BRK 
100A  BRK 

When  jumping  forward,  you  often  do  not  yet  know  the 
precise  address  you  want  to  branch  to.  In  the  example  above, 
we  really  wanted  to  go  to  $1008  when  the  loop  was  finished 
(when  X  was  equal  to  zero),  but  we  just  entered  an  approxi- 
mate address  ($100A)  and  made  a  note  of  the  place  where  this 
guess  appeared  ($1004).  Then,  using  the  direct  memory 
changing  function  in  the  monitor,  we  can  change  location 
$1004  to  the  correct  offset  when  we  know  what  it  should  be. 

Forward  counting  is  easy.  When  we  learned  that  we 
wanted  to  go  to  $1008,  we  would  change  the  number  $5  in 
address  $1004  to  $3. 

Remember  that  you  start  counting  from  zero  from  the  ad- 
dress immediately  following  the  branch  instruction.  For  ex- 
ample, a  jump  to  $1008  would  be  three  because  you  count 
$1005  =  0,  $1006  =  1,  $1007=2,  $1008=3.  All  this  confusion 
disappears  after  writing  a  few  programs  and  practicing  with 
estimated  branch  addresses.  Luckily,  the  assembler  does  all 
the  backward  branches.  That's  lucky  because  they  are  much 
harder  to  calculate. 


U 
LJ 


Unknown  Forward  Branches  1 I 

If  you  are  using  LADS,  all  branches  are  given  names  rather 

than  addresses.  These  names  are  called  labels,  and  they  are  ;    i 

automatically  calculated  for  you  by  the  assembler.  You  would  ' — ' 
write  the  above  example  with  LADS  in  this  way: 
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ldx  #o 

COUNTUP  INX 

BEQ  MORETHINGS  ;or  any  other  label  you  want 

to  give  it 
JMP   COUNTUP  ;jumps  also  have  labels  as 

their  targets 
MORETHINGS  BRK 

With  LADS  and  other  advanced  assemblers,  you'll  gen- 
erally want  to  use  labels  instead  of  actual  addresses.  This 
makes  things  pretty  easy  on  the  programmer.  LADS  does 
much  of  the  busywork  for  you,  particularly  if  you  make  good 
use  of  its  pseudo-ops.  By  the  way,  pseudo-ops  are  essentially 
instructions  directly  to  the  assembler,  such  as  "please  insert 
the  following  as  pure  ASCII  text,"  but  which  are  not  normal 
8502  instructions  that  get  translated  into  ML  object  code.  In- 
stead, a  pseudo-op  is  a  request  to  the  assembler  program  to 
perform  some  extra  service  for  the  programmer.  We'll  go  into 
them  in  detail  later. 

Absolute,X  and  Absolute, Y 

Another  important  mode  provides  you  with  an  easy  way  to 
access  lists  or  tables.  This  method  looks  like  absolute  address- 
ing, but  you  attach  an  X  or  a  Y  to  the  address.  The  X  and  Y 
stand  for  the  X  and  Y  registers,  which  are  being  used  in  this 
technique  as  offsets.  That  is,  if  the  X  register  contains  the  num- 
ber 3,  then  whatever  address  you  type  in  will  have  3  added  to 
it.  If  X  holds  a  3  and  you  type  LDA  $1000,X,  you  will  LoaD 
Accumulator  with  the  value  (number)  which  is  in  memory  cell 
$1003.  The  register  value  is  added  to  the  absolute  address. 

Another  addressing  method  called  zero  page,X  works  the 
same  way:  LDA  $05,X.  (Load  from  cell  5  plus  whatever's  in 
the  X  register.)  These  indexed  addressing  modes  let  you  easily 
transfer  or  search  through  messages,  lists,  or  tables.  Error  mes- 
sages can  be  sent  to  the  screen  using  such  a  method.  Assume 
that  you  set  it  up  so  that  the  words  SYNTAX  ERROR  are  held 
in  some  part  of  memory  because  you  sometimes  need  to  send 
them  to  the  screen  from  your  program.  You  might  have  a 
whole  table  of  such  messages.  But  we'll  say  that  the  words 
SYNTAX  ERROR  are  stored  at  address  $3000.  Your  screen 
memory  address  is  1024  ($0400  hex);  here's  how  you  would 
send  the  message: 
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1000    LDX 
1002    LOOP 
1005    BEQ 


#$00 
LDA 
QUIT 


1007 
100A 


STA 

INX 


100B    JMP       LOOP 
1010    QUIT    BRK 


Set  the  counter  register  to  zero. 

$3000,X   Get  a  letter  at  3000  +  X. 

If  the  letter  is  a  zero,  we've  reached 
the  end  of  the  message,  so  we 
branch  to  the  end  of  this  routine. 

$0400,X    Send  the  letter  to  0400  +  X. 

Increment  the  counter  so  that  the 

next  letter  in  the  message  as  well  as 

the  next  screen  position  are  pointed 

to. 

Jump  to  the  load  instruction  to  fetch 

the  next  character. 

Task  completed,  message  transferred. 

This  sort  of  indexed  looping  is  an  extremely  common  ML 
programming  device.  It  can  be  used  to  create  delays  (FOR  T  =  1 
TO  5000:  NEXT  T),  to  transfer  any  chunk  of  memory  to  an- 
other place,  to  check  the  status  of  memory  (to  see,  for  ex- 
ample, if  a  particular  word  appeared  somewhere  on  the 
screen),  and  to  perform  many  other  tasks.  It  is  a  fundamental, 
all-purpose  machine  language  technique. 

Here's  a  fast  way  to  fill  your  screen  or  any  other  area  of 
memory.  This  is  a  full  source  code  for  the  demonstration 
screen-fill  example  we  tried  in  Chapter  1.  See  if  you  can  fol- 
low how  this  indexed  addressing  works.  What  bytes  are  filled 
in  and  when?  At  ML  speeds,  it  isn't  necessary  to  fill  them  in 
order — nobody  would  see  an  irregular  filling  pattern  because, 
like  magic,  it  all  happens  too  fast  for  the  eye  to  see  (see  Pro- 
gram 4-2). 

Program  4-2.  Filling  the  Screen  with  the  letter  A 


10  *=  $B00 

20  .0 

30  .S 

40  A  =  $01; 

SCREEN  CODE  FOR  "A" 

50  ; 

60  LDY  #0; 

SET  COUNTER  TO  ZERO 

70  LDA  #A 

80  STA  $0400, Y 

90  STA  $0500, Y 

100  STA  $0600, Y 

110  STA  $0700, Y 

120  INY; 

RAISE  COUNTER  BY  1 

130  BNE  LOOP; 

IF  Y  IS  NOT  YET  ZER( 

140  RTS 

u 
u 
u 
u 
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Compare  this  with  the  program  on  page  xii  to  see  the  ef- 
fects of  using  a  different  screen  starting  address  and  how 
source  code  is  a  more  elaborate  version  of  what  you  get  when 
you  run  the  monitor's  disassembler  to  get  an  ML  program 
listing. 

Indirect  Y 

This  addressing  mode  is  a  real  workhorse;  you'll  use  it  often. 
Several  of  the  examples  in  this  book  refer  to  it  and  explain  it 
in  context.  The  argument  you  use  with  this  mode  isn't  so 
much  an  address  in  itself  as  a  method  of  creating  an  address.  It 
looks  like  this: 

4000  STA  ($80),  Y 

Seems  innocent  enough.  That  Y  works  like  the  other 
kinds  of  index  modes  we've  discussed  before.  Whatever  is  in 
the  Y  register  is  added  to  the  final  address. 

But  watch  out  for  those  parentheses.  They  mean  that  $80 
is  not  the  real  address  here.  We're  not  going  to  put  the  byte  in 
the  accumulator  into  address  $80  plus  the  value  of  Y.  Instead, 
addresses  $80  and  $81  are  themselves  holding  the  address  we 
are  sending  our  byte  to.  We  are  not  sending  to  $0080;  hence, 
the  name  for  this  mode  is  indirect  Y. 

Where  does  the  byte  in  the  accumulator  end  up?  It  de- 
pends what  address  you've  stored  in  bytes  $80  and  $81.  If  $80 
and  $81  have  these  numbers  in  them: 

$0080  01 
$0081  20 

and  Y  is  holding  a  5,  then  the  byte  in  A  will  end  up  in  ad- 
dress $2006.  How  did  we  get  $2006? 

First,  you've  got  to  mentally  swap  the  numbers  in  $80 
and  $81.  The  8502  requires  that  address  pointers  be  listed  in 
backward  order:  The  pointer  is  holding  $2001,  not  $0120. 
Then,  you've  got  to  add  the  value  in  the  Y  register,  5,  and  you 
get  $2006. 

This  is  a  valuable  tool,  even  if  it's  perplexing  at  first.  You 
should  familiarize  yourself  with  it.  It  lets  you  get  easy  access 
to  many  memory  locations  very  quickly  by  just  changing  the  Y 
register  (using  INY  or  DEY)  or  by  directly  changing  the  ad- 
dress pointer  itself  (using  INC  or  DEC,  instructions  that  raise 
or  lower  a  byte  in  RAM  memory  by  one).  You  can  make  rad- 
ical shifts  with  this  pointer-changing  technique.  You  can  shift 
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up  a  whole  page  (256  bytes)  by  simply  INC  $81:  That  will  j     j 

change  your  target  address  from  $2001  to  $2101.  To  go  down  ' — ' 

four  pages,  subtract  four  from  address  $81.  Combine  this  with 
the  indexing  that  the  Y  register  is  doing  for  you,  and  you've  |    I 

got  greater  efficiency,  greater  reach  to  all  the  RAM  you  want  — ' 

to  manipulate. 

Right  now  you're  paying  the  only  price  you'll  ever  pay  for  \    i 

this  valuable  tool:  It's  possibly  the  most  perplexing  thing  ' — ' 

when  you're  learning  ML.  You've  got  to  try  it  a  few  times, 
scratch  your  head,  and  get  the  concept. 

Let's  clear  away  some  of  the  fog.  How  were  those  bytes  at 
$80  and  $81  selected  to  be  the  ones  holding  our  indirect  ad- 
dress? The  programmer  decides  where  address  pointers  are 
stashed  (they  must  be  in  zero  page).  You  figure  out  where  the 
safe  places  are  in  zero  page,  and  you  use  them  for  your  point- 
ers. That's  the  main  use  that  you'll  have  for  zero  page. 
Remember  that  the  creators  of  the  128  set  aside  zero  page 
bytes  $FA  through  $FE  for  our  use.  The  128  leaves  them 
alone,  so  there's  room  for  two  of  your  indirect  Y  pointers  in 
that  safe  area. 

How  did  the  numbers  $20  and  $01  get  into  the  pointer  in 
the  example  above?  The  programmer  put  them  there.  As  part 
of  the  initial  activities  of  an  ML  program,  you  stick  byte-pairs 
(these  address  pointers)  into  zero  page.  If  you're  using  a  sim- 
ple assembler,  you'll  need  to  keep  a  record  of  the  pointers  on 
paper.  If  you're  using  LADS,  you  give  the  pointers  labels  like 
this: 

SCREENPOINTER  =  $80 

And  you  can  also  have  a  label  for  the  actual  screen  address: 

SCREEN  =  $0400 

Then,  to  set  up  a  pointer,  you  use  some  pseudo-ops  in  LADS 
which  break  a  two-byte  address  like  $0400  into  halves  for 
storage  in  pointers: 

LDA  #<SCREEN;  loads  the  low  byte 

STA  SCREENPOINTER 

LDA  #>SCREEN;  loads  the  high  byte 

STA  SCREENPOINTER +1;    stores  into  address  SCREENPOINTER 

plus  1  ($81) 

When  an  address  is  set  up  in  a  pointer,  it's  split  in  half. 
The  address  $0400  was  split  in  the  example  above.  When 
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programming  in  ML,  it's  useful  to  distinguish  between  the  two 
halves  by  saying  that  one  of  the  bytes  is  the  LSB  (least  signifi- 
cant byte)  and  the  other  is  the  MSB  (most  significant  byte).  In 
our  example,  the  $00  is  the  LSB,  and  the  $04  is  the  MSB. 
That's  not  because  one  number  is  smaller  than  the  other; 
rather,  it's  because  they  are  in  different  positions  in  the  two- 
byte  address.  The  position  on  the  left  is  of  far  more  signifi- 
cance than  the  position  on  the  right  in  $0400.  It's  the  same  for 
decimal  numbers:  5015  when  chopped  in  half  means  that  the 
left  half  stands  for  fifty  100's  and  the  right  half  only  stands  for 
fifteen  l's.  Clearly  the  right  position  is  the  less  significant. 

Note  that  every  time  you  add  one  to  the  MSB  of  a  double- 
byte  hex  number  in  ML,  you  are  adding  one  page,  256.  This  is 
how  you  can  INC  or  DEC  the  MSB  of  your  pointer  and  move 
quickly  through  the  "pages"  of  memory.  And,  remember,  you 
store  pointers  in  reverse  order  when  you  are  setting  up  a 
pointer,  LSB,  MSB: 

0080  00 

0081  04;  a  pointer  to  the  screen  memory  of  the  128 

Indirect  X 

This  addressing  mode  is  rarely  used.  It  makes  it  possible  to  set 
up  a  group  of  pointers,  a  cluster  of  them,  in  zero  page.  It's  like 
indirect  Y,  except  the  X  register  value  is  not  added  to  the  ad- 
dress pointer  to  form  the  ultimate  address  target.  Rather,  X 
points  to  the  pointer  you  desire  to  use.  Nothing  is  added  to  the 
address  held  in  the  pointer.  It  looks  like  this: 

5000  STA  ($90,X) 

To  see  it  in  action,  let's  assume  that  you've  already  set  up 
a  cluster  of  pointers  in  zero  page.  It's  a  table  of  pointers,  not 
just  one: 

0090  $00;  Pointer  1 

0091  $04;  points  to  $0400 

0092  $05;  Pointer  2 

0093  $70;  points  to  $7005 

0094  $EA;  Pointer  3 

0095  $81;  points  to  $81EA 

If  X  holds  a  2  when  we  STA  ($90,X),  then  the  byte  in  the 
accumulator  will  be  sent  to  address  $7005.  If  X  holds  a  4,  the 
byte  will  go  to  $81EA. 
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All  things  considered,  this  addressing  mode  has  little  to 
recommend  it.  If  you  set  up  the  same  table,  you  could  access 
these  pointers  just  as  easily  and  have  the  flexibility  of  that  Y 
index  into  the  bargain.  Who  knows  why  the  designers  of  the 
8502  chip  included  this  mode? 

Accumulator  Mode 

ASL,  LSR,  ROL,  and  ROR  shift  the  bits  in  the  byte  held  in  the 
accumulator.  We'll  touch  on  this  shifting  in  Chapter  6  when 
we  discuss  the  instruction  set.  This  mode  doesn't  really  have 
much  to  do  with  addressing  as  such,  but  it's  always  listed  as  a 
separate  mode. 

Zero  Page,Y 

This  mode  can  be  used  with  only  two  instructions:  LDX  and 
STX.  Otherwise,  it  operates  just  like  zero  page,X  discussed 
above. 

What  to  Remember 

There  you  have  them,  13  addressing  modes  to  choose  from. 
However,  there  are  only  six  that  you  should  focus  on.  Try 
practicing  with  them  until  you  understand  their  uses:  immedi- 
ate, absolute  (plus  absolute,X  and  ,Y),  zero  page,  and  indirect 
Y.  The  rest  are  either  unimportant  when  you're  programming 
because  they  are  automatic  (like  the  implied  mode)  or  are  not 
really  worth  bothering  with.  Now  that  we've  surveyed  the 
ways  you  can  move  numbers  around,  it's  time  to  see  how  to 
do  arithmetic  in  ML. 
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There'll  be  many  things  that  you'll  want  to  do  in  ML,  but 
complicated  math  is  not  one  of  them.  Mathematics  beyond 
simple  addition,  subtraction,  multiplication,  and  division  will 
not  be  covered  in  this  book.  For  games  and  most  other  ML  for 
personal  computing,  you  won't  need  to  use  complex  math.  In 
this  chapter  we'll  cover  what  you  are  likely  to  use.  BASIC  is 
well-suited  to  sophisticated  mathematical  programming  and  is 
far  easier  to  work  with  for  such  tasks.  If  you're  planning  a 
program  that's  going  to  involve  trigonometry  or  quadratic 
equations,  use  BASIC. 

But  before  we  look  at  ML  arithmetic,  let's  briefly  review 
an  important  concept:  how  the  computer  tells  the  difference 
between  addresses,  numbers  as  such,  and  instructions.  It  is 
valuable  to  be  able  to  visualize  what  the  computer  is  going  to 
do  as  it  comes  upon  each  byte  in  your  ML  routine. 

Even  when  a  computer  appears  to  be  working  with 
words,  letters  of  the  alphabet,  graphics  symbols,  and  the  like, 
it  is  still  working  with  numbers.  A  computer  works  only  with 
numbers.  The  ASCII  code  is  a  convention  by  which  a  com- 
puter understands  that  when  the  context  is  alphabetic,  the 
number  65  means  the  letter  A.  At  first  this  is  confusing.  How 
does  it  know  when  65  is  A  and  when  it  is  just  65?  And  there's 
a  third  possibility:  The  65  could  represent  the  cell  65  in  the 
computer's  memory,  the  sixty-fifth  address. 

It  is  worth  remembering  that,  like  us,  the  computer  means 
different  things  at  different  times  when  it  uses  a  symbol  (like 

j—|  65).  We  can  mean  a  street  address  by  it,  a  temperature,  or  a 

'     '  code.  We  could  agree  that  whenever  we  used  the  symbol  65, 

we  were  ready  to  leave  the  party.  We  would  look  meaning- 

f— ]  fully  at  our  companion  and  say,  "Everyone  expects  to  retire  at 

1  -  '  sixty-five."  Then  hope  they  get  the  hint  and  remember  the 

code. 

i— I  The  point  is  that  symbols  aren't  anything  in  themselves. 

'    I  They  stand  for  other  things,  and  what  they  stand  for  must  be 

agreed  upon  in  advance.  There  must  be  rules.  A  code  is  an 

j— I  agreement  in  advance  that  one  thing  symbolizes  another. 
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The  Computer's  Rules 

Inside  your  machine,  at  the  most  basic  level,  there  is  a  stream 
of  input.  The  stream  flows  continually  past  a  "gate"  like  a 
river  through  a  canal.  For  99  percent  of  the  time,  the  128  sees 
a  continuous  stream  of  88's. 

When  you  first  turn  it  on,  the  computer  just  sits  there. 

What's  it  doing?  It  will  be  updating  its  clock,  and  it's 
holding  things  coherent  on  the  TV  screen — but  it  mainly  waits 
in  an  endless  loop  for  you  to  press  a  key  on  your  keyboard  to 
let  it  know  what  it's  supposed  to  do. 

There  is  a  memory  cell  inside  your  128  which  the  com- 
puter constantly  checks.  This  byte  in  the  128  is  located  at  $D4. 
While  no  key  is  pressed,  $D4  holds  the  number  88.  When  a 
key  is  hit  on  the  keyboard,  however,  a  different  number  ap- 
pears in  $D4,  a  number  unique  to  the  key  pressed  called  its 
keyboard  matrix  code.  This  isn't  the  same  as  the  ASCII  code 
that  you  use  to  print  to  the  screen.  However,  you  can  use  this 
matrix  code  to  make  branches  and  decisions  just  as  well  as 
any  other  code.  For  example,  anything  other  than  88  in  $D4 
signals  that  someone  is  typing  something  on  the  keyboard.  If 
the  RETURN  key  is  pressed,  a  1  will  appear  in  location  $D4. 
Finally,  after  centuries  (the  computer's  sense  of  time  differs 
from  ours)  here  is  something  to  work  with.  Something  has 
come  up  to  the  gate  at  last. 

But  assume  that  someone  hits  the  RETURN  key,  and  a  1 
appears  in  location  $D4.  You  notice  the  effect  at  once — every- 
thing on  the  screen  moves  up  one  line,  because  1  (in  the  key- 
board matrix  code)  stands  for  a  carriage  return.  How  did  the 
128  know  that  you  were  not  intending  to  type  the  number  1 
when  it  saw  1  in  the  keyboard  sampling  cell?  Simple.  The 
number  1,  and  any  other  keyboard  input,  is  always  read  from  ,     , 

$D4  as  a  keyboard  matrix  code  number.  Besides,  there's  a  dif-  I I 

ference  between  the  number  1  and  the  ASCII  or  matrix  codes 

for  the  character  1.  ,    , 

Let's  look  at  this  a  slightly  different  way.  Say  that  some-  ! I 

one  typed  in  the  number  141  on  they  keyboard.  The  matrix 

code  for  each  of  those  three  characters  1,  4,  and  1  would  ap-  ,    i 

pear,  in  turn,  in  cell  $D4  for  as  long  as  each  key  was  being  I ! 

pressed.  But,  in  the  matrix  code  or  ASCII,  the  digits  from  0 

through  9  are  the  only  number  symbols.  There  is  no  single  ,     , 

symbol  for  the  three  characters  14  1.  So,  when  you  type  in  a  I ! 

1  followed  immediately  by  a  4  and  then  another  1,  the 
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computer's  input-from-keyboard  routine  notices  that  you  have 
not  pressed  one  of  the  "instant  action"  keys  (such  as  the  ESC, 
TAB,  or  cursor-control  keys).  Rather,  you  typed  1  and  4  and 
another  1 — the  keyboard  sampling  cell,  the  "which  key 
pressed"  location  in  zero  page  at  $D4,  received  the  matrix 
code  for  1,  and  then  for  4,  and  finally  another  1.  And,  in  be- 
tween each  of  these  codes,  it  received  88  showing  that  the  hu- 
man, operating  at  slow  human  speeds,  was  not  pressing  any 
keys  for  a  time. 

The  point  is  that  hitting  the  key  labeled  1  followed  by  the 
key  labeled  4  followed  by  another  1  is  not  storing  those  num- 
bers into  that  sampling  cell  at  $D4.  Instead,  these  keypresses 
are  stored  as  characters.  On  the  ML  level,  numbers  are  distinct 
from  characters.  A  character  like  3  has  an  ASCII  and  matrix 
code  value  which  differs  from  its  numeric  value.  In  other 
words,  typing  14  1  will  not  result  in  the  computer  seeing  a  1, 
a  4,  and  a  1.  Type  in  this  little  BASIC  program  to  see  what's 
happening  in  $D4: 

10  PRINT  PEEK(212);:GOTO  10 

and  then  type  on  the  keyboard.  Each  key  has  a  different  ma- 
trix value.  What  happens  when  you  SHIFT  or  ESC  a  key? 

Incidentally,  128's  ASCII  code  representations  (as  distinct 
from  the  matrix  code)  of  the  digits  are  easy  to  remember  in 
hex:  0  is  $30,  1  is  $31,  ...  up  to  $39  for  9.  In  decimal,  the  dig- 
its would  be  48  through  57.  The  matrix  code  follows  no 
particular  pattern. 

The  point  of  all  this  is  that  the  computer  decides  the 
"meaning"  of  the  numbers  which  flow  into  and  through  it  by 
each  number's  context.  If  it  is  in  "alphabetic"  mode,  the  com- 
puter will  see  the  number  65  as  A;  or  if  it  has  just  received  an 
r™l  A,  it  might  see  a  subsequent  number  65  as  an  address  to  store 

the  A.  It  all  depends  on  the  events  that  surround  a  given  num- 
ber. We  can  illustrate  this  with  a  simple  example: 

f~]  2000    LDA  #$C1     $A9  (169)    $C1  (193) 

2002    STA  $C1        $85    (133)    $C1   (193) 

This  short  ML  program  (the  numbers  in  parentheses  are 
the  decimal  values)  shows  how  the  computer  can  "expect"  dif- 
ferent meanings  from  the  number  193  ($C1  hex).  When  it  re- 
ceives an  instruction  to  perform  an  action,  it  is  then  prepared 
to  act  upon  a  number.  The  instruction  comes  first  and,  since  it 
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is  the  first  thing  the  computer  sees  when  it  starts  a  job,  it  , 

knows  that  the  number  $A9  (169)  is  not  a  number.  I | 

It  has  to  be  one  of  the  ML  instructions  from  its  set  of 
instructions  (see  Appendix  A). 

I_J 
Instructions  and  Their  Arguments 

The  computer  would  no  more  think  of  this  first  169  as  the 

number  169  than  you  would  seal  an  envelope  before  the  letter  j | 

was  inside.  If  you  are  sending  out  a  pile  of  Christmas  cards, 
you  perform  instruction-argument  just  the  way  the  computer 
does:  You  (1)  fill  the  envelope  (instruction)  (2)  with  a  card 
(argument,  or  operand).  You  don't  get  the  envelopes  confused 
with  the  cards  and  try  to  stuff  an  envelope  into  a  card. 

All  actions  do  something  to  something.  A  computer's  ac- 
tion is  called  an  instruction  (or,  in  its  numeric  form  as  part  of 
an  ML  program  inside  the  computer's  memory,  it's  called  an 
opcode  for  operation  code).  The  target  of  the  action  is  called  its 
argument,  or  operand.  In  our  program  above,  the  computer 
must  LoaD  Accumulator  with  193.  The  #  symbol  means  im- 
mediate; the  target  is  right  there  in  the  next  memory  cell 
following  the  LDA  instruction,  so  it  isn't  supposed  to  be 
fetched  from  a  distant  memory  cell.  That  193,  however,  is  not 
another  instruction;  it's  the  number  193. 

Then,  after  this  action  has  been  completed,  after  the  accu- 
mulator contains  the  number  193,  the  next  number  (the  133 
which  means  STore  Accumulator  in  zero  page,  the  first  256 
cells)  must  be  an  instruction,  the  start  of  another  complete  ac- 
tion. And,  once  again,  the  computer  knows  that  the  instruction 
133  must  be  followed  by  an  address  of  a  cell  in  memory  to 
store  to.  So,  in  the  example,  we've  got  a  total  of  four  numbers: 
169,  193,  133,  and  193.  If  you  PEEKed  at  this  little  ML  rou- 
tine, you'd  find  these  numbers  in  this  order.  But  when  this  ML  i_J 
program  is  run,  is  executed  by  the  8502,  it  will  see  169  as  an 
instruction,  193  as  a  number,  133  as  another  instruction,  and 
the  193  following  that  instruction  as  an  address  in  memory.  j     j 
Instructions,  numbers,  addresses — they  are  all  mixed  in  to- 
gether, but  the  chip  can  figure  out  which  is  which  based  upon 

their  context.  It  knows  that  LDA  #  will  be  followed  by  a  sin-  j j 

gle-byte  number  because  that's  what  LDA  in  the  immediate 
addressing  mode  demands.  The  computer  would  no  more  ex- 
pect an  address  to  come  after  LDA  #  than  you  would  expect  j [ 

someone  to  say  "1700  Taylor  Street"  when  you  asked  what 
time  it  was. 
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__  Think  of  the  computer  as  completing  each  action  and  then 

!     |  looking  for  another  instruction.  It  moves  through  your  list  of 

instructions  logically.  Recall  from  the  last  chapter  that  the  tar- 

_  get  can  be  "implied"  in  the  sense  that  INX  simply  increases 

i     I  the  X  register  by  one.  The  one  is  "implied"  by  the  instruction 

itself,  so  there  is  no  target  argument  in  these  cases.  The  next 

_^  cell  in  this  case  must  also  contain  an  instruction  for  a  new 

|     I  instruction-argument  cycle. 

Some  instructions  call  for  a  single-byte  argument.  LDA 
#193  is  of  this  type.  You  cannot  LoaD  Accumulator  with  any- 
thing greater  than  255.  The  accumulator  is  only  one  byte 
large,  so  anything  that  can  be  loaded  into  it  can  also  be  only  a 
single  byte  large.  (Recall  that  255,  $FF,  is  the  largest  number 
that  can  be  represented  by  a  single  byte.) 

STA  $C1  also  has  a  one-byte  argument  because  the  target 
address  for  the  STore  Accumulator  is,  in  this  case,  in  zero 
page. 

Storing  to  zero  page  or  loading  from  it  will  need  only  a 
one-byte  argument — the  address.  Zero  page  addressing  is  a 
special  case,  but  an  assembler  program  will  take  care  of  it  for 
you.  It  will  pick  the  correct  opcode  for  this  addressing  mode 
when  you  type  LDA  $C1.  Typing  in  LDA  $000  would  create 
ML  code  that  performs  the  same  operation,  though  it  would 
use  three  bytes  instead  of  two  to  do  it. 

But  how  does  the  chip  know  that  a  given  instruction  is 
self-contained  like  the  INY,  implied  addressing  mode?  Or  an- 
other instruction  uses  up  two  bytes  like  zero  page  addressing 
(STA  $15  uses  one  byte  for  the  STA  command  and  one  byte 
for  the  $15)?  Or  the  biggest  addressing  modes,  like  STA 
$1500,  absolute  addressing,  take  three  bytes  before  they  can 
look  for  the  next  instruction  in  a  program? 

f"~|  Inside  the  chip  is  a  program  counter  (PC).  It  has  a  list  of  all 

the  ML  instructions.  And  it  knows  how  many  bytes — one, 
two,  or  three — that  each  instruction  takes  up.  During  an  ML 

'*"]  program's  execution,  the  program  counter  acts  like  a  finger 

that  keeps  track  of  where  the  computer  is  located  at  any  given 
time  in  its  trip  up  the  series  of  ML  instructions  that  comprise 

I"""]  your  program.  Each  instruction  takes  up  one,  two,  or  three 

bytes,  depending  on  what  type  of  addressing  is  going  on.  The 
program  counter  looks  at  its  list  and  moves  up  the  appropriate 

["""]  number  of  bytes  to  show  where  the  next  instruction  will  be. 
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Context  Defines  Meaning  ,    . 

TXA  uses  only  one  byte,  so  the  program  counter  moves  ahead  I I 

one  byte  and  stops  and  waits  until  the  value  in  the  X  register 

is  moved  over  into  the  accumulator.  TXA  is  supposed  to  trans-  .     i 

fer  into  the  accumulator  whatever  number  is  in  the  X  register.  I I 

Then  the  computer  asks  the  PC,  "Where  are  we?"  and  the  PC 

is  pointing  to  the  address  of  the  next  instruction.  The  PC  ,  - , 

never  points  to  an  argument.  It  skips  over  them  because  it  I I 

knows  how  many  bytes  each  addressing  mode  uses  up  in  a 
program. 

Say  that  the  next  instruction  after  TXA  is  LDA  $15.  This 
is  a  two-byte-long,  zero  page  addressing  mode.  The  PC  looks 
on  its  list  and  moves  up  two  bytes.  The  longest  possible 
instruction  would  use  three  bytes,  such  as  LDA  $5000  (ab- 
solute addressing).  The  PC  counts  up  three  and  points.  Your 
assembler  would  translate  LDA  $15  into  $A5  and  POKE  it.  It 
would  translate  LDA  $1500  into  $AD  and  POKE  that.  Since 
the  opcodes  that  get  POKEd  are  different,  even  though  the 
LDA  mnemonics  are  identical,  the  computer  can  know  how 
many  bytes  a  given  instruction  will  use  up.  That's  how  it 
knows  where  the  next  instruction  must  be  in  your  program. 

Having  reviewed  the  way  that  your  computer  makes 
contextual  sense  out  of  the  mass  of  seemingly  similar  numbers 
of  which  an  ML  program  is  composed,  we  can  now  move  on 
to  see  how  elementary  arithmetic  is  performed  in  ML. 

Addition 

Arithmetic  is  performed  in  the  accumulator.  The  accumulator 
holds  the  first  number,  the  target  address  holds  the  second 
number  (but  is  not  affected  by  the  activities),  and  the  result  is 
left  in  the  accumulator.  So, 

LDA  #$40   Remember,  the  #  means  immediate,  the  $  means  hex.  I — I 

ADC  #$01 

will  result  in  the  number  $41  being  left  in  the  accumulator.  j    I 

We  could  then  STA  that  number  wherever  we  wanted.  Simple  ' — ' 
enough. 

The  ADC  means  ADd  with  Carry.  If  an  addition  results  in  j    I 

a  number  higher  than  256  (if  we  added,  say,  250  +  7),  then  ' — ' 
there  would  have  to  be  a  way  to  show  that  the  number  left 

behind  in  the  accumulator  isn't  the  correct  result — that  what's  j    | 

in  the  accumulator  isn't  the  total,  it's  the  carry.  ' — J 
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,— |  After  adding  250  +  7,  you  would  find  a  1  in  the  accu- 

I    [  mulator,  and  the  carry  flag  would  be  up. 

That  means  that  you  must  add  256  to  whatever  is  in  the 
accumulator  to  find  the  real  answer:  257. 

To  make  sure  that  things  never  get  confused,  always  CLC 
(dear  the  Carry  flag)  before  you  do  any  addition.  CLC  will  push 
the  carry  flag  down  (in  case  it  was  up  from  some  previous 
event  in  your  program).  Then,  if  you  find  that  it  is  up  after  the 
addition  (ADC),  you'll  know  that  you  need  to  add  256  to 
whatever  is  in  the  accumulator.  You'll  know  that  the  accu- 
mulator is  holding  the  carry,  not  the  total  result. 

One  other  point  about  the  status  register:  There  is  another 
flag,  the  decimal  flag.  If  you  ever  set  this  flag  up  (with  the 
SED,  SEt  Decimal  instruction),  all  addition  and  subtraction  is 
performed  in  a  decimal  mode  in  which  the  carry  flag  is  set 
whenever  an  addition  exceeds  99.  In  this  book,  we  are  not  go- 
ing into  the  decimal  mode  at  all.  Decimal  mode  has  little  value 
in  ML  programming.  It's  another  one  of  those  things  that 
sounds  good,  but  doesn't  do  much  in  practice. 

Adding  Numbers  Larger  Than  255 

We  have  already  discussed  the  idea  of  setting  aside  some 
memory  cells  as  a  table  for  data.  To  do  this,  we  simply  make  a 
note  to  ourselves  that,  say,  addresses  $D6  and  $D7  are  de- 
clared a  zone  for  our  personal  use  as  a  storage  area.  Using  a 
typical  example,  let's  think  of  this  two-byte  zone  as  the  place 
that  holds  the  address  of  a  "moving  finger"  going  through  a 
list  of  names  we've  stored  in  RAM.  As  long  as  the  zone  is  not 
in  ROM  or  used  by  our  program  elsewhere  or  used  by  the 
computer  (see  the  memory  map  in  Appendix  C  or  use  the  safe 
r— )  areas  like  $FA-$FE  we  discussed  earlier),  it's  fine  to  declare  an 

<    I  area  a  data  zone.  It  is  a  good  idea  (especially  with  longer  pro- 

grams) to  make  notes  on  a  piece  of  paper  to  show  where  you 
i— i  intend  to  have  your  subroutines,  your  main  loop,  your 

L  }  initialization,  and  your  miscellaneous  data — names,  messages 

for  the  screen,  input  from  the  keyboard,  and  so  on.  This  is  one 
r— ,  of  those  things  that  BASIC  does  for  you  automatically,  but 

I  J  which  you  must  do  for  yourself  in  ML.  However,  you  can  set 

up  data  zones  with  the  LADS  assembler  by  using  the  .BYTE, 
r—.  =,  or  *=  pseudo-ops.  It's  generally  a  good  idea  to  put  mes- 

f    j  sage  tables,  and  so  forth,  at  the  very  end  of  your  program. 
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When  BASIC  creates  a  string  variable,  it  sets  aside  an  area 
to  store  variables.  This  is  what  DIM  does.  In  ML,  you  set  aside  J^_j 

your  own  areas  by  simply  finding  a  clear  memory  space  and 
not  writing  a  part  of  your  program  into  it  (or  by  staking  out 

some  memory  with  .BYTE  or  *  =  in  LADS).  Part  of  your  data  \ \ 

zone  can  be  special  registers  you  declare  to  hold  the  results  of 
addition  or  subtraction. 

But  back  to  our  example:  You  might  make  a  note  to  your-  \ J 

self  that  after  finding  these  zero  page  locations  safe  to  use, 
$D6  and  $D7  will  hold  the  current  position  within  a  list  of 
names  in  your  database.  This  is  a  pointer,  and  we  can  look  at 
all  the  bytes  within  our  database  by  adjusting  this  pointer  in 
$D6  and  $D7.  In  this  way  we  can  efficiently  search  through 
the  database. 

Since  the  "moving  finger"  searching  through  the  database 
is  constantly  in  motion,  this  pointer  will  be  changing  all  the 
time  as  it  looks  for  your  target  information.  Notice  that  you 
need  two  bytes  for  this  pointer.  That  is  because  one  byte  could 
hold  only  a  number  from  0  through  255.  Two  bytes  together, 
though,  can  hold  a  number  up  to  65535  (all  the  possible  ad- 
dresses in  the  128  without  bank  switching). 

To  define  the  pointer  location,  you  could  do  this  in  LADS: 

FINGER  =  $D6 

If  you  needed  another  two-byte  pointer  to  hold  another  ad- 
dress, you  could  write  this: 

OTHER  =  $EB 

and  so  on,  using  safe  areas,  for  as  many  pointers  as  you 
needed. 

Since  your  128  can  address  only  a  total  of  65536  memory 
cells  with  any  single  instruction,  two-byte  registers  like  these 

can  address  any  addressable  cell  in  your  current  bank.  So  if  l \ 

your  "moving  finger"  is  supposed  to  look  up  the  name 
"Mitchell,  Nancy"  in  the  database,  you'll  want  to  start  off  by 
looking  for  the  letter  M.  In  setting  up  your  list  of  names,  you 
decided  that  each  entry,  each  record,  would  be  given  40  bytes 
of  space.  Thus,  you  are  going  to  be  adding  40  to  the  FINGER 
if  the  first  character  in  the  first  record  isn't  an  M.  Let's  say  that 
the  list  of  records  starts  in  memory  at  address  $8000. 

Before  accessing  the  list,  we  punch  in  the  target  address: 

LDA  #0:STA  $D6:LDA  #$80:STA  $D7 


i     i 


\     i 


I     i 
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nOr  you  could  accomplish  the  same  thing  with  the  LADS 
assembler  by  using  labels  and  the  #>  and  #<  pseudo-ops 
which  extract  the  MSB  and  LSB  of  a  label's  address: 


n 


n 


i  > 


n 
n 


LDA  #<DATA:STA  FINGER:LDA  #>DATA:STA  FINGER +1. 

The  FINGER  address  register  now  looks  like  this  in  the 
monitor:  $00D6  00  80  (remember  that  the  higher,  most  signifi- 
cant byte,  comes  after  the  LSB,  the  least  significant  byte).  To 
move  to  the  next  name  in  the  list,  we  want  FINGER  to  be 
$00D6  28  80.  (The  28  is  hex  for  40.)  In  other  words,  we're  go- 
ing to  move  the  finger  up  one  record  in  the  database  list.  To 
do  this,  we  need  to  add  $28  (40  decimal)  to  the  pointer,  the 
FINGER. 

Remember  the  indirect  Y  addressing  mode  which  lets  us 
use  an  address  in  zero  page  as  a  pointer  to  another  address  in 
memory?  The  number  in  the  Y  register  is  added  to  whatever 
address  sits  in  $D6  and  $D7,  so  we  don't  STA  to  $D6  or  $D7, 
but  rather  to  the  address  that  they  contain:  STA  ($D6),Y. 

How  to  add  $28  to  the  FINGER  pointer?  First  of  all,  CLC 
(CLear  the  Carry)  to  be  sure  that  flag  is  down.  This  example  is 
written  for  the  mini-assembler  in  the  monitor: 

1000  CLC  $1000  is  the  location  of  our  "add  40  to  FINGER" 

subroutine. 

1001  LDA  $D6      We  fetch  the  LSB  of  FINGER. 
1003    ADC  #$28    Add  40. 

1006    STA    $D6  Put  the  new  result  into  FINGER. 

1008    LDA  $D7  Get  the  MSB  of  FINGER. 

100A  ADC  #$00  Add  with  carry  to  the  MSB  of  FINGER. 

1010    STA    $D7  Update  FINGER'S  MSB. 

That's  it.  Any  carry  will  automatically  set  the  carry  flag  up 
during  the  ADC  action  on  the  LSB  and  will  be  added  into  the 
result  when  we  ADC  to  the  MSB.  It's  all  quite  similar  to  the 
way  that  we  add  numbers,  putting  a  carry  onto  the  next  col- 
umn when  we  get  more  than  a  ten  in  the  first  column.  And 
this  carrying  is  why  we  always  CLC  (clear  the  carry  flag;  put  it 
down)  just  before  additions.  If  the  carry  is  set,  we  could  get 
the  wrong  answer  if  our  problem  did  not  result  in  a  carry.  Did 
the  addition  above  cause  a  carry?  (Remember,  we  started  with 
a  value  of  $8000  in  FINGER.) 

Note  that  we  need  not  check  for  any  carries  during  the 
MSB + MSB  addition.  Any  carries  resulting  in  a  database  ad- 
dress greater  than  $FFFF  (65535)  would  be  impossible  on  our 
machines. 
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The  8502  is  permitted  to  address  $FFFF  tops,  under  nor-  .    } 

mal  conditions.  However,  it  is  possible  to  add  numbers  larger  I I 

than  65535  by  simply  using  more  than  two  bytes  and  continu- 
ing to  add  with  carry  across  a  multibyte  chain.  ,    , 

The  example  above  would  be  somewhat  easier  with  L_ni 
LADS  because  you  would  substitute  label  names  (FINGER  and 

DATA,  in  this  case)  for  the  numbers.  Also,  you  could  define  ^     , 

another  label  to  hold  the  size  of  a  record  (RECORD  =  40),  i_J 
and  then  line  1003  would  read  ADC  #RECORD. 

Subtraction 

As  you  might  expect,  subtracting  single-byte  numbers  is  a 
snap: 

LDA  #$41 
SBC    #$01 

results  in  a  $40  being  left  in  the  accumulator.  As  before, 
though,  it's  important  to  make  it  a  habit  to  deal  with  the  carry 
flag  before  each  calculation.  When  subtracting,  however,  you 
set  the  carry  flag:  SEC.  Why  is  unimportant.  Just  always  SEC 
before  any  subtractions,  and  your  answers  will  be  correct. 
Here's  double  subtracting  that  will  move  the  FINGER  back 
down  one  record  in  the  data  list: 

$1020    SEC  $1020  is  where  we  arbitrarily  decided  to  locate 

our  "take  40  from  FINGER"  subroutine. 

1021    LDA  $D6  Get  the  LSB  of  FINGER. 

1023    SBC    #$28  LSB  of  the  size  of  a  single  record. 

1026    STA   $D6  Put  the  new  result  into  FINGER. 

1028    LDA  $D7  Get  FINGER's  MSB. 

102A  SBC    #$00  Subtract  the  MSB  of  the  size  of  a  single  record. 

102D  STA   $D7  Update  FINGER's  MSB. 

Multiplication  and  Division  ' — ' 

Multiplying  could  be  done  by  repeated  adding.  To  multiply  5 

X  4,  you  could  just  add  4  +  4  +  4  +  4  +  4.  One  way  would  i    I 

be  to  set  up  two  registers  like  the  ones  we've  used  before.  ' — ' 

Both  registers  (or  storage  zones)  could  contain  a  4,  and  then 

you  could  loop  through  an  add-these-two-registers  subroutine  \    ) 

five  times.  For  practical  purposes,  however,  multiplying  and  '-— ' 

dividing  are  more  easily  accomplished  in  BASIC.  They  are 

simply  not  worth  the  trouble  of  setting  up  in  ML,  especially  if  j    / 

you  need  to  involve  decimal-point  fractions  (floating-point  ' — ' 
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arithmetic).  Perhaps  surprisingly,  for  games  and  most  personal 
computing  tasks  where  ML  routines  and  programs  are  created, 
there  is  little  use  either  for  negative  numbers  or  arithmetic  be- 
yond simple  addition  and  subtraction.  When  we  get  into  di- 
vision and  multiplication,  we've  gone  beyond  the  simple 
arithmetic  that  you'll  need — unless  you're  writing  an  account- 
ing program  or  a  spreadsheet  program. 

If  you  find  that  you  do  need  complicated  mathematical 
structures,  create  the  program  in  BASIC,  adding  ML  where  su- 
per speeds  are  desirable.  Such  hybrid  programs  are  efficient 
and,  in  their  way,  elegant. 

One  final  note:  An  easy  way  to  divide  the  number  in  the 
accumulator  by  two  is  to  LSR.  Try  it.  Similarly,  you  can  mul- 
tiply by  two  with  ASL.  We'll  define  LSR  and  ASL  in  the  next 
chapter.  If  you're  interested  in  using  these  techniques,  take  a 
look  at  the  "Library  of  Subroutines"  (Appendix  E). 

Double  Comparison 

One  rather  tricky  technique  is  used  fairly  often  in  ML  and 
should  be  learned.  It  is  tricky  because  two  of  the  B  branching 
instructions  seem  to  be  worth  using  in  this  context,  but  are 
best  avoided  for  this  kind  of  comparing.  If  you're  trying  to 
keep  track  of  the  location  of  a  record  within  a  database,  this 
will  be  a  two-byte  address.  If  you  need  to  compare  those  two 
bytes  against  another  two-byte  address,  you'll  need  a  "double- 
compare"  subroutine.  You  might,  for  example,  want  to  check 
whether  or  not  one  record  is  located  higher  in  the  database 
than  another. 

Double-compare  is  also  useful  in  any  other  ML  where  you 
need  to  manipulate  numbers  larger  than  can  be  held  in  one 
byte  (where  the  single  CMP  instruction  would  be  able  to  com- 
pare them  for  you). 

The  problem  is  the  BPL  instruction  (Branch  on  PLus)  and 
its  companion,  BMI  (Branch  on  Minus).  Don't  use  them  for 
comparisons.  In  any  comparisons,  whether  single-  or  double- 
byte,  use  BEQ  to  test  if  two  numbers  are  equal,  BNE  for  not 
equal,  BCS  for  equal  or  higher,  and  BCC  for  lower.  You  can 
remember  BCS  because  its  S  is  higher  and  BCC  because  its  C  is 
lower  in  the  alphabet.  Program  5-1  shows  one  easy  way  to 
perform  a  double-compare. 
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Program  5-1.  Double-Compare 


10  *=  $B00 

20  .S 

30  .0 

40  START  SEC 

50  LDA  TESTED; 

COMPARE 

;  THE  LOW  BYTES 

60  SBC  SECOND 

70  STA  TEMP 

80  LDA  TESTED+1; 

COMPARE 

1  THE  HIGH  BYTES 

90  SBC  SECOND+1 

100  ORA  TEMP 

110  BEQ  EQUAL; 

TESTED 

=  SECOND 

120  BCC  LOWER; 

TESTED 

<  SECOND 

130  BCS  HIGHER; 

TESTED 

>  SECOND 

140  ; 

T  A  MH  T  MP 

160  LOWER  BRK 

"  JjAjNUXWU 

xrJj/\v-r.o     ™        ~""* 

170  EQUAL  BRK 

180  HIGHER  BRK 

omr\D  7\(T 

"  olUKALrrj 

500  TEMP  .BYTE  0 

600  SECOND  .BYTE 

0  0 

700  TESTED  .BYTE 

0  0 

710  .END  5-1 

u 


u 


This  is  LADS  at  work.  Recall  that  with  assemblers  like 
LADS,  you  can  use  line  numbers  and  labels,  add  numbers  to 
labels  (see  the  TESTED  +  1  in  line  80),  add  comments,  and 
all  the  rest. 

To  try  out  this  double  comparison,  type  in  the  source 
code  in  Program  5-1.  Then  assemble  it  with  LADS.  Now  go 
into  the  monitor  with  F8,  and  type  D  $B00  to  see  the  results 
of  your  assembly.  Notice  the  eight  zeros  at  the  end  of  the  little 
program.  You  can  then  try  putting  different  numbers  into  ■ 

TESTED  and  SECOND  and  reassemble  (or  just  insert  them  in  J j 

the  monitor  using  the  >  monitor  memory  change  command). 

Notice  that  the  numbers  being  compared  are  not  really  (    , 

interchangeable.  One  is  the  "tested"  number,  and  the  other  is  J_J 

the  number  it  is  being  tested  against,  the  one  we're  calling 
SECOND  in  our  label  scheme  here.  As  you  can  see,  you've 

got  to  keep  it  straight  in  your  mind  which  number  is  being  [ J 

tested,  or  the  results  won't  make  much  sense. 

When  you've  set  up  two  double-byte  numbers  in  the  reg- 

isters  (TESTED  and  SECOND),  you  can  run  this  routine  from  j j 

within  the  monitor  by  typing  G  BOO.  All  that  will  happen  is 
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|—|  that  you  will  land  on  a  BRK  instruction  and  halt  further  activ- 

ity. Where  you  land  tells  you  the  results  of  the  comparison.  If 
the  numbers  are  equal,  you  land  at  EQUAL'S  address.  If  the 
f— "]  tested  number  is  less  than  the  second  number,  you'll  end  up 

'     l  in  the  location  of  LOWER,  and  so  forth.  (The  monitor  will 

give  a  PC  number  which  is  two  bytes  above  the  actual  BRK 
r*|  instruction,  so  take  that  into  account.) 

'    '  You  could  test  using  only  a  BNE  if  all  you  needed  to 

know  is  whether  or  not  the  two  numbers  are  equal.  You  could 
leave  out  some  of  these  branch  tests  if  you're  not  interested  in 
them.  Play  around  with  this  until  you've  understood  the  ideas 
involved. 

In  a  real  program,  you  would  be  branching  to  addresses 
in  your  ML  program  which  do  something  if  the  numbers  under 
comparison  are  equal  or  one  is  greater  or  whatever.  This  ex- 
ample sends  the  computer  to  LOWER,  EQUAL,  or  HIGHER, 
where  it  comes  to  an  abrupt  halt  just  to  let  you  see  the  effects 
of  a  double-compare  subroutine,  but  in  a  real  program  EQUAL 
would  be  the  start  of  a  subroutine  which  accomplished  some- 
thing based  on  the  discovery  of  equality.  Above  all,  remember 
that  you  should  use  BCC  and  BCS  {not  BPL  or  BMI)  when 
comparing  in  ML. 

Some  might  wonder  why  we  use  CMP  to  test  the  low 
bytes  and  then  switch  to  SBC  to  test  the  high  bytes.  It's  just  a 
convenience.  CoMPare  is  a  subtraction  of  one  number  from 
another.  The  only  difference  between  CMP  and  SBC,  really,  is 
that  subtraction  replaces  the  number  in  the  accumulator  with 
the  result.  LDA  #5:SBC  #2  will  leave  3  in  the  accumulator. 
Using  LDA  #5:CMP  #2  leaves  the  5  in  the  accumulator,  and 
all  that  happens  is  that  flags  are  affected.  Both  SBC  and  CMP 
p— I  have  an  effect  on  the  zero,  negative,  and  carry  flags.  In  our 

'    *  double-compare  we  don't  care  if  there  is  a  result  left  in  the 

accumulator  or  not.  So,  we  can  use  either  SBC  or  CMP.  The 
n  reason  for  starting  off  with  CMP,  however,  is  that  we  don't 

'    '  have  to  SEC  (set  the  carry  flag)  as  we  always  need  to  do 

before  an  SBC. 
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'  !      The  Instruction  Set 


-   '  There  are  56  instructions  (commands)  available  in  8502  ma- 

chine language.  Most  versions  of  BASIC  have  about  50  com- 
|— "J  mands.  Some  BASIC  instructions  are  rarely  used  by  the 

1  majority  of  programmers,  for  example,  END,  SGN,  TAN,  USR. 

Some,  such  as  LET,  contribute  nothing  to  a  program  and  seem 
to  have  remained  in  the  language  for  nostalgic  reasons.  Oth- 
ers, like  TAN,  have  uses  that  are  highly  specialized. 

There  are  surplus  commands  in  computer  languages  just 
as  there  are  surplus  words  in  English.  People  don't  often  say 
culpability.  They  usually  just  say  guilt.  The  message  gets 
across  without  using  the  entire  dictionary.  The  simple,  com- 
mon words  can  do  the  job. 

Machine  language  is  the  same  as  any  other  language  in 
this  respect.  There  are  around  20  heavily  used  instructions. 
The  36  remaining  ones  are  used  far  less  often.  You  can  switch 
into  the  128's  monitor  with  F8  and  look  at  part  of  your 
computer's  ROM.  To  look  at  BASIC  ROM,  once  in  the  mon- 
itor, type  D  F4000  and  press  RETURN.  To  see  more,  press  D 
and  RETURN.  You  can  now  read  the  machine  language 
routines  which  comprise  BASIC.  You'll  find  interesting  things 
all  the  way  from  $4000  up  to  $FFFF  in  bank  15.  You'll  also 
quickly  discover  that  the  accumulator  is  heavily  trafficked 
(LDA  and  STA  appear  frequently  in  the  disassembly),  but  you 
will  have  to  hunt  to  find  BVC,  CLV,  ROR,  RTI,  or  SED. 

ML,  like  BASIC,  offers  you  many  ways  to  accomplish  the 
same  job.  Some  programming  solutions,  of  course,  are  better 
f— i  than  others,  but  the  main  thing  is  to  get  the  job  done.  An  in- 

'    '  fluence  still  lingers  from  the  early  days  of  computing  when 

memory  space  was  rare  and  expensive.  This  influence — that 
j— I  you  should  try  to  write  programs  using  up  as  little  memory  as 

'    '  possible — can  be  safely  ignored.  Efficient  memory  use  will 

often  be  at  the  bottom  of  your  list  of  objectives  when  program- 
r-i  ming  ML.  It  could  hardly  matter  whether  you  use  25  instead 

'  of  15  bytes  to  print  a  message  to  the  screen  when  your  com- 

puter has  space  for  programming  which  exceeds  130,000  bytes. 

Rather  than  memorize  each  ML  instruction  individually, 
we  will  concentrate  on  the  workhorses.  Bizarre  or  arcane 
instructions  will  get  only  passing  mention.  Unless  you  are 
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planning  to  use  ML  programs  to  interface  to  strange 
peripherals  or  need  to  do  complex  mathematical  calculations 
and  such,  you  will  be  able  to  write  excellent  machine  language 
programs  for  nearly  any  application  with  the  instructions  we'll 
focus  on  in  this  book. 

For  each  instruction  group,  we  will  describe  three  things 
before  getting  down  to  the  details  about  programming  with  ,     > 

them:  (1)  what  the  instructions  accomplish,  (2)  the  addressing  1 1 

modes  you  can  use  with  them,  and  (3)  what  they  do,  if  any- 
thing, to  the  flags  in  the  status  register.  A  condensed,  reference 
version  of  this  information  is  also  found  in  Appendix  A. 

The  Six  Instruction  Groups 

The  best  way  to  approach  the  instruction  set  might  be  to  break 
it  down  into  the  following  six  categories  which  group  the 
instructions  according  to  their  functions: 

1.  Transporters 

2.  Arithmetic  Group 

3.  Decision  Makers 

4.  Loop  Group 

5.  Subroutine  and  Jump  Group 

6.  Debuggers 

We  will  deal  with  each  group  in  order,  pointing  out 
similarities  to  BASIC  and  describing  the  major  uses  for  each. 

As  always,  the  best  way  to  learn  is  by  doing.  Move  bytes 
around.  Use  each  instruction,  typing  a  BRK  as  the  final 
instruction  to  see  the  effects.  If  you  LDA  #65,  look  in  the  A 
register  to  see  what  happened.  Then,  STA  $12  and  check  to 
see  what  was  copied  into  address  $12.  If  you  send  the  byte  in 
the  accumulator  (STA),  what  is  left  behind  in  the  accumulator? 
Is  it  better  to  think  of  bytes  being  copied  rather  than  being  )    I 

sent?  "     '  L~ ' 

Play  with  each  instruction  to  get  a  feel  for  it.  Discover  the 
effects,  qualities,  and  limitations  of  these  ML  commands.  !    I 
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1.  The  Transporters: 

LDA,  LDX,  LDY 

STA,  STX,  STY 

TAX,TAY 

TXA,TYA 

r^  These  instructions  move  a  byte  from  one  place  in  memory  to 

I    (  another.  To  be  more  precise,  they  copy  whatever  value  is  in  a 

source  location  into  a  target  location.  The  source  location  still 
contains  the  byte,  but  after  a  "transporter"  instruction,  a  copy 
of  the  byte  is  also  in  the  target  location.  This  does  replace 
whatever  used  to  be  in  the  target. 

All  of  them  affect  the  N  and  Z  flags,  except  STA,  STX, 
and  STY  which  do  nothing  to  any  flag. 

There  are  a  variety  of  addressing  modes  available  to  dif- 
ferent instructions  in  this  group.  Check  the  chart  in  Appendix 
A  for  specifics. 

Remember  that  the  computer  does  things  one  at  a  time. 
Unlike  the  human  brain  which  can  carry  out  a  thousand  dif- 
ferent instructions  simultaneously  (walk,  talk,  and  smile,  all  at 
once),  the  computer  goes  from  one  tiny  job  to  the  next.  It 
works  through  a  series  of  instructions,  raising  the  program 
counter  (PC)  each  time  it  handles  an  instruction. 

If  you  do  a  TYA,  the  PC  goes  up  by  one  to  the  next  ad- 
dress, and  the  computer  looks  at  that  next  instruction.  STA 
$80  is  a  two-byte-long  instruction;  it's  zero  page  addressing, 
so  PC = PC +  2.  STA  $8600  is  a  three-byte-long  absolute 
addressing  mode,  and  PC = PC +3  automatically. 

Recall  that  there's  nothing  larger  than  a  three-byte  in- 
crement of  the  PC.  However,  in  each  case,  the  PC  is  cranked 
up  the  right  amount  to  make  it  point  to  the  address  for  the 

I    (  next  instruction.  Things  would  quickly  get  out  of  control  if  the 

PC  pointed  to  some  argument  (some  address)  thinking  it  was 

.  an  instruction.  It  would  be  incorrect  (and  soon  disastrous)  if 

]    \  the  PC  pointed  to  the  $15  in  LDA  $15. 

If  you  type  SYS  15000  from  BASIC,  the  program  counter 
is  loaded  with  15000,  and  the  computer  transfers  control  to 

/    i  the  ML  instructions  which  are  (we  hope)  sitting  at  address 

15000  (decimal)  on  up.  It  will  then  look  at  byte  15000  (deci- 
mal), expecting  it  to  be  an  instruction.  Since  the  computer 
does  all  this  very  fast,  it  can  seem  to  be  keeping  score,  bounc- 
ing the  ball,  moving  the  paddle,  and  everything  else — simulta- 
neously. It's  not,  though.  It's  flashing  from  one  task  to  another 
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and  doing  it  so  fast  that  it  creates  the  illusion  of  simultaneity  , 

much  the  way  that  24  still  pictures  per  second  look  like  mo-  J | 

tion  in  movies. 

The  Programmer's  Time  Warp  j [ 

Movies  are,  of  course,  lots  of  still  pictures  flipping  by  in  rapid 
succession.  Computer  programs  are  composed  of  lots  of  in- 
dividual instructions  performed  in  rapid  succession.  j f 

Grasping  this  sequential,  step-by-step  activity  makes  our 
programming  job  easier:  We  can  think  of  large  programs  as 
single  steps,  coordinated  into  meaningful,  harmonious  actions. 
Now  the  computer  will  put  a  blank  over  the  ball  at  the  ball's 
current  address,  then  adjust  the  ball  address  to  move  it 
slightly  downward  on  the  screen,  then  print  the  ball  character 
to  the  new  address.  The  main  single-step  action  is  moving 
information,  as  single-byte  numbers,  from  here  to  there,  in 
memory.  We  are  always  creating,  updating,  modifying,  mov- 
ing, and  destroying  single-byte  variables.  The  moving  is  gen- 
erally done  from  one  double-byte  address  to  another.  But  it  all 
looks  smooth  to  the  player  during  a  game. 

Programming  in  ML  can  pull  you  into  an  eerie  time  warp. 
You  might  spend  several  hours  constructing  a  program  which 
executes  in  seconds.  You  are  putting  together  instructions 
which  will  later  be  read  and  acted  upon  by  coordinated  elec- 
trons, moving  at  electron  speeds.  It's  as  if  you  spent  an  after- 
noon slowly  and  carefully  drawing  up  pathways  and  patterns 
which  would  later  be  a  single  bolt  of  lightning. 

Registers 

In  ML  there  are  three  primary  places  where  variables  rest 

briefly  on  their  way  to  memory  cells:  the  X,  the  Y,  and  the  A 

registers.  And  the  A  register  (the  accumulator)  is  the  most  fre-  |_J 

quently  used;  X  and  Y  are  used  for  looping  and  indexing.  Each 

of  these  registers  can  grab  a  byte  from  anywhere  in  memory 

or  can  grab  the  byte  from  the  address  right  after  its  own  Lj 

opcode  (immediate  mode  addressing): 

LDY  $8000          Puts  the  number  at  hex  address  8000  into  Y,  with-                .     , 
out  destroying  it  at  $8000.  I 1 

LDY  #65  Puts  the  decimal  number  65  into  Y.  (Remember,  with 

the  128's  built-in  monitor,  you'd  need  to  add  a  + 
sign  in  front  of  the  65  to  have  the  mini-assembler  j     J 

consider  the  65  a  decimal  value:  LDA  #+65.) 

LDA  and  LDX    Work  the  same. 
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Be  sure  you  understand  what  is  happening  here.  LDY 
$1500  does  not  copy  the  byte  in  the  Y  register  into  address 
$1500.  It's  just  the  opposite.  The  number  (or  value,  as  it's 
sometimes  called)  in  $1500  is  copied  into  the  Y  register.  This 
is  LoaD  Y. 

To  copy  a  byte  from  X,  Y,  or  A,  use  STX,  STY,  or  STA. 
For  these  "store-bytes"  instructions,  however,  there  is  no  im- 
mediate addressing  mode.  No  STA  #$15.  It  would  make  no 
sense  to  have  STA  #$15.  That  would  be  disruptive,  for  it 
would  modify  the  ML  program  itself.  It  would  put  the  number  15 
into  the  next  cell  beyond  the  STA  instruction  within  the  ML  pro- 
gram itself. 

Another  type  of  transporter  moves  bytes  between  reg- 
isters—TAX,  TAY,  TXA,  TYA.  See  the  effect  of  writing  the 
following.  Look  at  the  registers  after  executing  this: 

1000    LDA  #$65 

1002  TAY 

1003  TAX 

The  number  $65  is  placed  into  the  accumulator,  then 
transferred  to  the  Y  register,  then  sent  from  the  accumulator  to 
X.  All  the  while,  however,  the  A  register  (the  accumulator)  is 
not  being  emptied.  Sending  bytes  is  not  a  transfer  in  the  usual 
sense  of  the  term  sending.  It  is  more  as  if  a  photocopy  were 
made  of  the  number,  and  then  the  copy  was  sent.  The  original 
stays  behind  after  the  copy  is  sent. 

LDA  #$15  followed  by  TAY  would  leave  the  $15  in  the 
accumulator,  sending  a  copy  of  $15  into  the  Y  register. 

Notice  that  you  cannot  directly  move  a  byte  from  the  X  to 
the  Y  register  or  vice  versa.  There  is  no  TXY.  or  TYX. 

Flags  Up  and  Down 

Another  effect  of  moving  bytes  around  is  that  it  sometimes 
throws  a  flag  up  or  down  in  the  status  register.  LDA  (or  LDX 
or  LDY)  will  affect  the  N  and  Z,  negative  and  zero,  flags. 
We  will  ignore  the  N  flag.  It  changes  when  you  used 
"signed  numbers,"  a  special  technique  to  allow  for  negative 
numbers.  For  our  purposes,  the  N  flag  will  fly  up  and  down 
all  the  time,  and  we  won't  care.  We  won't  pay  any  attention  to 
it;  we  won't  test  to  see  where  it  is.  If  you're  curious,  signed 
numbers  are  manipulated  by  allowing  the  seven  bits  on  the 
right  to  hold  the  number,  the  leftmost  bit  to  stand  for  positive 
or  negative.  We  normally  use  a  byte  to  hold  values  from  0 
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through  255.  If  we  were  working  with  "signed"  numbers,  any-  ,    , 

thing  higher  than  127  would  be  considered  a  negative  number  ! 

since  the  leftmost  bit  would  be  "on" — and  an  LDA  #255 

would  be  thought  of  as —1.  ,     . 

This  is  another  example  of  how  the  same  thing  (the  num-  |_J 

ber  255  in  this  case)  can  signify  several  different  conditions, 
depending  on  the  context  in  which  it  is  being  interpreted. 

The  Z  flag,  on  the  other  hand,  is  quite  important;  we  can't  1_J 

ignore  this  flag.  It  shows  whether  or  not  some  action  during  a 
program  run  resulted  in  a  zero.  The  branching  instructions  and 
looping  depend  on  this  flag,  and  we'll  deal  with  the  important 
zero-result  effects  below  with  the  BNE  and  INX  instructions, 
and  so  on. 

No  flags  are  affected  by  the  STA,  STX,  or  STY  instruction. 

The  Stack  Can  Take  Care  of  Itself 

There  are  some  instructions  which  move  bytes  to  and  from  the 
stack.  These  are  for  advanced  ML  programmers.  PHA  and 
PLA  copy  a  byte  from  A  to  the  stack  and  vice  versa.  PHP  and 
PLP  move  the  status  register  to  and  from  the  stack.  TSX  and 
TXS  move  the  stack  pointer  to  or  from  the  X  register.  Forget 
them.  Unless  you  know  precisely  what  you  are  doing,  you  can 
cause  havoc  with  your  program  by  fooling  with  the  stack.  The 
main  job  for  the  stack  is  to  hold  the  return  addresses  pushed 
into  it  when  you  JSR  Gump  to  SubRoutine).  Then,  when  you 
come  back  from  a  subroutine  (RTS),  the  computer  pulls  the 
addresses  off  the  stack  to  find  out  where  to  go  back  to. 

For  most  ML  programming,  avoid  stack  manipulation  un- 
til you  are  an  advanced  programmer.  If  you  manipulate  the 
stack  without  great  care,  you'll  cause  an  RTS  to  the  wrong  re- 
turn address,  and  the  computer  will  travel  far,  far  beyond  your 
control.  If  you  are  lucky,  it  sometimes  lands  on  a  BRK  instruc- 
tion and  you  fall  into  the  monitor  mode.  The  odds  are  that 
you  would  get  lucky  roughly  once  every  256  times.  Don't 
count  on  it.  Since  BRK  is  rare  in  your  BASIC  ROM,  the  J_J 

chances  are  pretty  low. 

You  could  fill  large  amounts  of  RAM  with  "snow"  by 

putting  zeros  everywhere.  This  greatly  improves  the  odds  that  j J 

a  crash  will  hit  a  BRK.  But  why  bother?  Play  it  safe  when 
you're  writing  a  program. 

As  an  aside,  there  is  another  use  for  snow,  a  blanket  of  j [ 

"zero  page  snow."  Recall  that  you  can  safely  use  some  loca- 
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tions  in  zero  page  (addresses  0-255),  but  that  your  computer 
and  many  commercial  programs  compete  for  space  in  zero 
page  because  it's  such  a  fast  place  to  access.  If  you  are  plan- 
ning to  modify,  say,  a  commercial  word  processor  and  need  to 
make  sure  that  it's  not  using  a  particular  area  of  zero  page  for 
its  own  purposes,  fill  zero  page  with  00  (snow),  put  the  word 
processor  through  its  paces,  and  then  take  a  look  at  the  tracks, 
the  nonzeros,  in  the  snow. 


2.  The  Arithmetic  Group: 
ADC,  SBC,  SEC,  CLC 

Here  are  the  commands  which  add,  subtract,  and  set  or  clear 
the  carry  flag.  ADC  and  SBC  trigger  the  N,  Z,  C,  and  V  (over- 
flow) flags.  CLC  and  SEC,  needless  to  say,  affect  the  C  flag, 
and  their  only  addressing  mode  is  implied. 

ADC  and  SBC  can  be  used  in  eight  addressing  modes:  im- 
mediate, absolute,  zero  page,  (indirect,X),  (indirect), Y,  zero 
page,X,  and  absolute,X  and  ,Y. 

Arithmetic  was  covered  in  the  previous  chapter.  To  re- 
view, the  carry  flag  must  be  cleared  with  CLC  before  any 
addition.  Before  any  subtraction,  it  must  be  set  with  SEC.  The 
decimal  mode  should  be  cleared  at  the  start  of  any  program 
(the  initialization)  with  CLD.  You  can  multiply  by  two  with 
ASL  and  divide  by  two  with  LSR.  You  can  divide  by  four  with 
LSR  LSR  or  by  eight  with  LSR  LSR  LSR.  You  could  multiply  a 
number  by  eight  with  ASL  ASL  ASL.  What  would  this  do  to  a 
number:  ASL  ASL  ASL  ASL?  To  multiply  by  numbers  which 
aren't  powers  of  two,  use  addition  plus  multiplication.  To  mul- 
tiply by  ten,  for  example,  copy  the  original  number  temporar- 
ily  to  a  vacant  byte  somewhere  in  memory.  Then  ASL  ASL 

I    |  ASL  to  multiply  it  by  eight.  Multiply  the  original  number  by 

two  with  a  single  ASL.  Then  add  them  together. 

If  you're  wondering  about  the  V  flag,  it  is  rarely  used  for 

)    (  anything.  You  can  forget  about  the  branch  which  depends  on 

it,  BVC,  too.  Only  five  instructions  affect  it,  and  it  relates  to 
twos  complement  arithmetic  which  we've  not  touched  on  in 

jj  this  book.  Like  decimal  mode  or  negative  numbers,  you  will 

be  able  to  construct  your  ML  programs  very  effectively  if  you 
remain  in  complete  ignorance  of  this  mode.  We  have  largely 

|    j  avoided  discussion  of  most  of  the  flags  in  the  status  register:  B, 

D,  I,  N,  and  V.  This  avoidance  has  also  removed  several  branch 

!     1  97 


Chapter  6 


u 
u 


instructions  from  our  consideration:  BMI,  BPL,  BVC,  and  BVS.  ,     , 

These  flags  and  instructions  are  not  usually  found  in  ML  pro-  LJ 

grams,  and  their  use  is  confined  to  specialized  mathematical  or 
interfacing  applications.  They  will  not  be  of  use  or  interest  to  ,     , 

the  majority  of  ML  programmers.  The  only  use  for  BPL  or  BMI  I 1 

which  might  interest  you  is  that  they  can  quickly  detect  whether 
a  character  is  shifted  above  128  in  value.  In  the  lower/uppercase  ,     , 

character  set,  small  a  is  65,  but  capital  A  is  193.  If  you  were  LJ 

going  through  a  list  of  names  and  the  way  you  had  arranged 
to  separate  them  was  by  shifting  the  first  letter  in  each  name, 
you  could  quickly  LDA  TARGET:BMI  SHIFTED  to  detect  that 
you  had  reached  the  end  of  a  particular  target  name.  Other- 
wise, forget  BPL  and  BMI. 

The  two  flags  of  interest  to  most  ML  programmers  are  the 
carry  flag  and  the  zero  flag.  That  is  why,  in  the  following  sec- 
tion, we  will  examine  only  the  four  branch  instructions  which 
test  the  C  and  Z  flags.  They  are  likely  to  be  the  only  branch- 
ing instructions  that  you'll  ever  find  occasion  to  use. 

3.  The  Decision  Makers: 
BCC,  BCS,  BEQ,  BNE,  CMP 

The  four  "branchers"  here — they  all  begin  with  a  B — have 
only  one  addressing  mode.  In  fact,  it's  an  interesting  mode 
unique  to  the  B  instructions  and  created  especially  for  them: 
relative  addressing.  They  do  not  address  a  memory  location  as 
an  absolute  thing;  rather,  they  address  a  location  which  is  just 
a  certain  distance  from  their  position  in  the  ML  code.  Put  an- 
other way,  the  argument  of  a  B  instruction  is  an  offset  which 
is  relative  to  the  position  of  the  instruction  itself.  You  never 
have  to  worry  about  relative  instructions  if  you  relocate  an  ML 
program,  if  you  locate  the  ML  program  in  some  other  place  in  \  J 

RAM  memory.  The  B  instructions  will  work  just  as  well  no  ""*" 

matter  where  your  ML  program  is  moved. 

That's  because  their  argument  just  says  "add  5  to  the  J j 

present  address"  or  "subtract  27"  or  whatever  argument  you 
give  them.  You  do  give  the  branchers  actual  addresses  as  you 

would  in  absolute  addressing:  BEQ  $3560.  However,  your  j [ 

assembler  will  translate  that  $3560  into  a  different,  somewhat 
strange,  number  that  is  used  in  relative  addressing.  (If  you  are 

using  an  advanced  assembler  like  LADS,  you  will  give  label  j [ 

names  as  the  argument  of  the  branchers  instead  of  actual  nu- 
meric addresses.) 
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nThe  branchers  cannot  branch  further  back  than  127  or  further 
forward  than  128  bytes. 

None  of  the  brancher  instructions  have  any  effect  whatso- 

never  on  any  flags;  instead,  they  are  the  instructions  which  look 
at  the  flags.  They  are  the  only  instructions  which  base  their 
activity  on  the  condition  of  the  status  register  and  its  flags. 

r— i  They're  why  the  flags  exist  at  all. 

I  -  l  CMP  is  an  exception.  Many  times  it  is  the  instruction  that 

comes  just  before  the  branchers  and  sets  flags  for  them  to  look 
at  and  make  decisions  about.  Lots  of  instructions — LDA  is 
one — will  set  or  clear  (put  down)  flags — but  sometimes  you 
need  to  use  CMP  to  find  out  what's  going  on  with  the  flags. 
CMP  affects  the  N,  Z,  and  C  flags.  CMP  has  many  addressing 
modes  available  to  it:  immediate,  absolute,  zero  page, 
(indirect,X),  (indirect), Y,  zero  page,X,  and  absolute,X  and  ,Y. 

You  might,  for  example,  LDA  NAME:CMP  SECOND- 
NAME  to  see  if  both  names  start  with  the  same  letter  (you 
would  BEQ)  or  if  they  don't  (BNE)  or  if  the  first  is  higher  than 
the  second  (BCS)  or  lower  (BCC).  In  all  these  cases,  you 
branch  based  on  what  the  CMP  did  to  the  flags.  Let's  take  a 
closer  look  at  what  branching  does  for  us  and  how  to  make 
the  best  use  of  it. 

The  Foundations  of  Computer  Power 

This  decision-maker  group  and  the  following  group  (loops)  are 
the  basis  of  our  computers'  enormous  strength.  The  decision 
makers  allow  the  computer  to  decide  between  two  or  more 
possible  courses  of  action.  This  decision  is  based  on  compari- 
sons. If  the  ball  hits  a  wall,  then  reverse  its  direction.  In 
BASIC,  we  use  IF-THEN  and  ON-GOTO  structures  to  make 
decisions  and  to  make  appropriate  responses  to  conditions  as 
they  arise  during  a  program  run. 

Recall  that  the  128  uses  memory-mapped  video  in  its  40- 
column  mode,  which  means  that  you  can  treat  the  screen  like 
an  area  of  RAM  memory.  You  can  PEEK  and  POKE  into  it  to 
create  animation,  text,  or  other  visual  events.  In  ML,  you 
PEEK  by  LDA  SCREEN  and  examine  what  you've  PEEKed 
with  CMP.  You  POKE  via  STA  SCREEN. 

CMP  does  comparisons.  It  tests  the  value  at  an  address 
against  what  is  in  the  accumulator.  Less  common  are  CPX  and 
CPY. 
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Assume  that  we  have  just  added  40  to  a  register  we  set  , 

aside  to  hold  the  current  address-location  of  FINGER  which  l^J 

points  to  records  in  our  database.  We  want  to  POKE  in  a  new 
record,  but  we  need  to  locate  a  vacant  record.  We  don't  want  ,    . 

to  cover  over  a  record  that's  in  use.  [_J 

In  practical  terms,  you  might  have  deleted  several  records 
within  your  database  and,  each  time  one  is  deleted,  you  just 

stick  a  zero  into  the  first  byte  of  the  record's  40-byte  space  to  ] j 

show  that  it's  empty.  Thus,  we  can  bounce  along  the  records, 
looking  at  the  first  byte  of  each,  to  find  an  available  empty 
record. 

Recall  that  the  very  useful  indirect  Y  addressing  mode  al- 
lows us  to  use  an  address  in  zero  page  as  a  pointer  to  another 
address  in  memory.  The  number  in  the  Y  register  is  added  to 
whatever  address  sits  in  $D6,$D7;  so  we  don't  LDA  from  $D6 
or  $D7,  but  rather  from  the  address  that  they  contain,  plus  Y's 
value. 

To  see  what's  in  the  first  byte  of  a  record,  we  can  do  the 
following: 

LDY  #$0  We  want  to  fetch  from  the  first  byte,  so  we  don't 

want  to  add  anything  to  it.  Y  is  set  to  zero. 

LDA  ($D6),Y     Fetch  whatever  is  sitting  there.  To  review  indirect,Y 
addressing  once  more,  say  that  the  address  we  are 
fetching  from  here  is  $1077.  Address  $D6  would 
hold  the  least  significant  byte,  LSB  ($77),  and  ad- 
dress $D7  would  hold  the  MSB  ($10).  Notice  that 
the  argument  of  an  indirect,Y  instruction  only  men- 
tions the  lower  address  of  the  two-byte  pointer,  the 
$D6.  The  computer  knows  that  it  has  to  combine 
$D6  and  $D7  to  get  the  full  address— and  it  does 
this  automatically. 

At  this  point,  we  might  come  upon  a  $CD  or  some  other 
number  which  we  would  know  indicated  that  this  record  was 
not  deleted.  Now  that  this  questionable  number  sits  in  the 
accumulator,  we  will  CMP  it  against  a  $0  which  signals  a  de- 
leted record.  We  could  compare  it  with  other  numbers,  too, 
numbers  which  we — in  setting  up  the  database — had  decided 
would  mean  "old  record"  or  "duplicated  record"  or  some 
other  housekeeping  information  which  would  help  us  in 
managing  the  data.  It  doesn't  matter.  The  main  thing  is  to 
compare  it  and  find  out  the  condition  of  this  particular  record: 
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2000    CMP  #$0       Is  it  a  zero? 

2002    BNE    $200A   Branch  if  Not  Equal  (if  not  zero)  to  address 
$200A,  which  contains  the  first  of  a  series  of 
comparisons  to  see  if  it's  an  "old"  or  "dupli- 
cated" record,  or  the  like.  On  the  other  hand,  if 
the  comparison  worked,  if  it  was  a  zero,  so  we 
didn't  Branch  Not  Equal,  then  the  next  thing 
that  happens  is  the  instruction  in  address 
$2004.  We  "fall  through"  the  BNE  to  an 
instruction  which  jumps  to  the  subroutine,  JSR, 
which  moves  the  new  record  into  the  vacant 
record  space,  thus  jumping  past  the  series  of 
comparisons  for  old,  duplicated,  and  so  forth. 
Insert  new  record  subroutine. 
Jump  over  the  rest  of  the  comparisons. 
Is  it  an  old  record? 
If  not,  continue  to  next  comparison. 
Perform  the  "old  records"  subroutine  and... 
jump  over  the  rest,  as  before  in  $2007. 
Is  it  a  duplicated  record?  ...  and  so  forth  with  as 
many  comparisons  as  needed. 

This  structure  is  to  ML  what  ON-GOTO  or  ON-GOSUB  is 
to  BASIC.  It  allows  you  to  take  multiple  actions  based  on  a 
single  LDA.  Doing  the  CMP  only  once  would  be  like  IF-THEN. 

Other  Branching  Instructions 

In  addition  to  the  BNE  we  just  looked  at,  there  are  BCC,  BCS, 
BEQ,  BMI,  BPL,  BVC,  and  BVS.  Learn  BCC,  BCS,  BEQ,  and 
BNE  and  you  can  safely  ignore  the  others. 

All  of  them  are  branching,  if-then,  instructions.  They 
work  in  the  same  way  that  BNE  does.  You  would  write  BEQ 
followed  by  the  address  you  want  to  go  to.  If  the  result  of  the 
comparison  is  "yes,  equal-to-zero  is  true,"  then  the  ML  pro- 
gram will  jump  (branch)  to  the  address  which  is  the  argument 
of  the  BEQ  instruction.  "True"  here  means  that  something 
EQuals  zero.  One  example  that  would  send  up  the  Z  flag 
(thereby  triggering  a  branch  with  BEQ)  is  LDA  #$00.  The  ac- 
tion of  loading  a  zero  into  the  accumulator  sets  the  Z  flag  up. 

You  are  allowed  to  branch  either  forward  or  backward 
from  the  address  that  holds  the  B  instruction.  However,  you 
cannot  branch  any  further  than  128  bytes  in  either  direction.  If 
you  want  to  go  further,  you  must  JMP  (JuMP)  or  JSR  Gump  to 


2004  JSR     $3000 

2007  JMP    $2020 

200A  CMP  #$1 

200C  BNE    $2014 

200E  JSR     $3050 

2011  JMP    $2020 

2014  CMP  #$2 
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SubRoutine).  For  all  practical  purposes,  you  will  usually  be  ,     , 

branching  to  instructions  located  within  30  bytes  of  your  B  L) 
instruction  in  either  direction.  You  will  be  taking  care  of  most 

things  right  near  where  the  CoMPare,  or  other  flag-flipping  {    , 

event,  takes  place.  l^J 

If  you  need  to  use  an  elaborate,  big  subroutine  which  can- 
not reside  within  128  bytes  of  a  branch,  simply  JSR  to  it  at  the  ■ 
target  address  of  your  branch:                                                                1 I 

2000    LDA   $65 

2002    CMP  $85        Is  what  was  in  address  65  equal  to  what  was  in 

address  85? 
2004    BNE    $2009     If  Not  Equal,  branch  over  the  next  three  bytes 

which  perform  some  elaborate  job. 
2006    JSR     $4000     At  $4000  sits  the  elaborate  subroutine  to  take 

care  of  cases  where  addresses  $65  and  $85  turn 

out  to  be  equal. 
2009  Continue  with  the  program  here. 

If  you  are  branching  backward,  you've  already  written 
that  part  of  your  program,  so  you  know  the  address  to  type  in 
after  a  BNE  or  one  of  the  other  branches.  But,  if  you  are 
branching  forward — to  an  address  in  part  of  the  program  not 
yet  written — how  do  you  know  what  to  give  as  the  address  to 
branch  to?  In  two-pass  assemblers  like  LADS,  you  can  just  use 
a  word  like  BRANCHTARGET,  and  the  assembler  will  pass 
twice  through  your  program  when  it  assembles  it.  The  first 
pass  simply  notes  that  your  BNE  is  supposed  to  branch  to 
BRANCHTARGET,  but  it  doesn't  yet  know  where  that  is. 

When  it  finally  finds  the  actual  address  of 
BRANCHTARGET,  it  makes  a  note  of  the  correct  address  in  a 
special  label  table.  Then,  it  makes  a  second  pass  through  the 
program  and  fills  in  (as  the  next  byte  after  your  BNE  or  what- 
ever) the  correct  address  of  BRANCHTARGET.  1_J 

All  of  this  is  automatic,  and  the  labels  make  the  program 
you  write  (called  the  source  code)  look  almost  like  English.  In 

fact,  assemblers  like  LADS  include  so  many  special  features  J { 

that  they  approach  higher-level  languages  like  BASIC: 

2000    TESTBYTE  =  $80           These  initial  definitions  of  (     , 

labels...  j ' 

2000    NEWBYTE  =  $FC  are  sometimes  called  equates. 

2000    LDA  #TESTBYTE 

2002    CMP  NEWBYTE  1     | 

2004    BNE  BRANCHTARGET  ,~J 
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(— I  2006    JSR  SUBROUTINE 

!.    I  BRANCHTARGET2009         ...etc. 

Instead  of  using  lots  of  numbers  (as  you  do  when  using 
|— I  the  built-in  mini-assembler  in  the  monitor)  for  the 

—  '  target/argument  of  each  instruction,  LADS  allows  you  to  de- 

fine (equate)  the  meanings  of  words  like  testbyte  and  then  use 
J— ]  the  word  instead  of  the  number.  And  LADS  does  simplify  the 

1  problem  of  forward  branching  since  you  just  give  (as  above) 

address  $2009  a  name,  BRANCHTARGET,  and  the  word  at 
address  $2005  is  later  replaced  with  $2009  when  the  assem- 
bler does  its  passes. 

Program  6-1  shows  how  the  example  above  looks  as 
source  code  to  be  fed  into  LADS. 

Actually,  we  should  point  out  in  passing  that  a  $2009  will 
not  be  the  number  which  finally  appears  at  address  $2005  to 
replace  BRANCHTARGET.  (Take  a  look  at  Program  6-1.)  As 
we  mentioned,  all  branches  are  relative,  an  offset  from  the  ad- 
dress of  the  branch.  The  number  which  will  finally  replace 
BRANCHTARGET  at  $2005  is,  as  you  can  see,  a  3.  This  is 
similar  to  the  way  that  the  value  of  the  Y  register  is  added  to 
an  address  in  zero  page  during  indirect  Y  addressing:  The 
number  given  as  an  argument  of  a  branch  instruction  is  added 
to  the  address  of  the  next  instruction.  So,  $2006  +  $3  = 
$2009.  If  this  seems  confusing,  forget  about  it.  LADS,  or  even 
the  mini-assembler  in  the  monitor,  will  take  care  of  all  this  for 
you.  All  you  need  to  do  is  give  $2009  as  the  argument  to  the 
mini-assembler,  or  a  label  name  to  LADS,  and  they  will  com- 
pute the  three  for  you. 

Forward  Branch  Solutions 

p"j  There  is  one  responsibility  that  you  do  have,  though,  if  you 

are  using  the  monitor's  mini-assembler.  When  you  are  writing 
2004  BNE  $2009,  how  do  you  know  to  write  in  $2009?  You 

ft  can't  yet  know  to  exactly  which  address  up  ahead  you  want  to 

branch.  There  are  two  ways  to  deal  with  this.  Perhaps  easiest 
is  just  to  put  in  BNE  $2004  (have  it  branch  to  itself).  This  will 

r~j  result  in  an  $FE  being  temporarily  left  as  the  target  of  your 

BNE.  Then,  you  can  make  a  note  on  paper  to  later  change  the 
byte  at  $2005  to  point  to  the  correct  address,  $2009.  You've 

j— ]  got  to  remember  to  "resolve"  that  $FE,  to  POKE  in  the  correct 

'  -'  offset  to  the  target  address,  or  you  will  leave  a  little  bomb  in 

your  program — an  endless  loop. 
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The  other,  even  simpler,  way  to  deal  with  forward  branch 
addresses  will  come  after  you  are  familiar  with  which  instruc- 
tions use  one,  two,  or  three  bytes.  The  BNE-JSR-TARGET 
construction  is  common  and  will  always  be  three  above  the 
next  address,  an  offset  of  three.  If  your  branch  instruction  is  at 
$2004,  you  just  add  two  to  get  the  next  address  ($2006),  then 
count  off  three:  $2006,7,8  and  write  BNE  2009. 

Other,  more  complex  branches  such  as  ON-GOTO  con- 
structions will  also  become  easy  to  count  off  when  you're 
familiar  with  the  instruction  byte  lengths.  In  any  case,  it's  sim- 
ple enough  to  make  a  note  of  any  unsolved  branches  and  cor- 
rect them  before  running  the  program. 

Of  course,  LADS  is  the  easiest  assembler  to  use  for  for- 
ward branching:  It  allows  you  to  branch  to  any  address  by  just 
giving  the  label  name  of  that  address. 

Recall  our  previous  warning  about  not  using  the  infamous 
BPL  and  BMI  instructions?  BPL  (Branch  on  PLus)  and  BMI 
(Branch  on  Minus)  sound  good,  but  should  be  avoided.  To  test 
for  less-than  or  more-than  situations,  use  BCC  and  BCS 
respectively.  (Actually,  the  BCS  test  is  "true"  for  greater-than- 
or-equal-to,  not  just  greater-than.)  Remember  that  BCC  is 
alphabetically  less-than  BCS — an  easy  way  to  remember  which 
to  use.  The  reasons  for  this  are  exotic.  We  don't  need  to  go  into 
them.  Just  be  warned  that  BPL  and  BMI  which  sound  so  logi- 
cal and  useful  are  not.  They  can  fail  you,  and  neither  one  lives 
up  to  its  name.  Stick  with  the  always  trustworthy  BCC,  BCS. 

Also  remember  that  BNE  and  the  other  three  main  B 
group  branching  instructions  often  don't  need  to  have  a  CMP 
come  in  front  of  them  to  affect  a  flag  that  can  be  tested  by  a 
following  B  instruction.  Many  actions  of  many  opcodes  will 
automatically  affect  flags.  For  example,  LDA  $80  will  affect 
the  Z  flag  so  that  you  can  tell  (using  BNE  or  BEQ)  if  the  num- 
ber in  address  $80  was  or  wasn't  zero.  LDA  $80  followed  by 
, — -  BNE  would  branch  away  if  there  were  anything  besides  a  zero 

L  >  in  address  $80.  If  in  doubt  about  which  flags  are  affected  by 

which  instructions,  check  Appendix  A.  You'll  soon  get  to 
i — |  know  the  common  ones.  If  you  are  really  in  doubt,  go  ahead 

i    !  and  stick  in  a  CMP.  It  can't  do  any  harm. 
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4.  The  Loop  Group: 
DEX,  DEY,  INX,  INY,  INC,  DEC 

INX  and  INY  raise  the  X  and  Y  register  values  by  one  each 

time  they  are  used.  If  Y  is  a  17  and  you  INY,  Y  becomes  an  I    j 

18.  Likewise,  DEX  and  DEY  decrease  the  values  in  these  reg-  ~"rJ 

isters  by  one.  There  is  no  such  increment  or  decrement 

instruction  for  the  accumulator. 

Similarly,  INC  and  DEC  will  raise  or  lower  a  memory  ad- 
dress by  one.  You  can  give  arguments  to  these  instructions  in 
four  addressing  modes:  absolute,  zero  page,  zero  page,X,  and 
absolute,X.  These  instructions  affect  the  N  and  Z  flags. 

The  loop  group  are  generally  used  to  set  up  FOR-NEXT 
structures.  The  X  register  is  used  most  often  as  a  counter  to 
allow  a  certain  number  of  events  to  take  place.  In  the  structure 
FOR  I  =  1  TO  10:NEXT  I,  the  value  of  the  variable  I  goes  up 
by  one  each  time  the  loop  cycles  around.  The  same  effect  is 
created  by: 

2000    LDX    #$0A     Decimal  10 

2002  DEX  "DEcrement"  or  "DEcrease  X"  by  one 

2003  BNE    $2002    Branch  if  Not  Equal  (to  zero)  back  up  to  ad- 

dress $2002 

Notice  that  DEX  is  tested  by  BNE  (which  sees  if  the  Z 
flag,  the  zero  flag,  is  up).  DEX  sets  the  Z  flag  up  when  X  fi- 
nally gets  down  to  zero  after  ten  cycles  of  this  loop.  The  only 
other  flag  affected  by  this  loop  group  is  the  N  (negative)  flag 
for  signed  arithmetic. 

Why  didn't  we  use  INX,  INcrease  X  by  one?  This  would 
parallel  exactly  the  FOR  1  =  1  TO  10,  but  it  would  be  clumsy 
since  our  starting  count  which  is  #10  above  would  have  to  be 
#245.  This  is  because  X  will  not  become  a  zero  going  up  until 

it  hits  255.  So,  for  clarity  and  simplicity,  it  is  customary  to  set  T j 

the  count  of  X  and  then  DEX  it  downward  to  zero.  The  follow- 
ing program  will  accomplish  the  same  thing  as  the  one  above 
and  allow  us  to  INX,  but  it  too  is  somewhat  clumsy:  J j 

2000  LDX  #$0 

2002  INX  ,     : 

2003  CPX  #$0A  LJ 
2005  BNE  $2002 

Here,  we  had  to  use  zero  to  start  the  loop  because,  right  ,    , 

off  the  bat,  the  number  in  X  is  INXed  to  one  by  the  instruction  LJ 

at  $2002.  In  any  case,  it  is  a  good  idea  simply  to  memorize  the 
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simple  loop  structure  in  the  first  example.  It  is  easy  and  ob- 
vious and  works  very  well. 


f— |  Big  Loops 

!  -  .  How  would  you  create  a  loop  which  has  to  be  larger  than  256 
cycles?  When  we  wanted  to  add  large  numbers,  numbers  too 
big  to  be  held  in  a  single  byte,  we  simply  used  two-byte  units 
instead  of  single-byte  units  to  hold  our  information.  Likewise, 
to  do  large  loops,  you  can  count  down  using  two  bytes  rather 
than  one.  In  fact,  this  is  quite  similar  to  the  idea  of  nested 
loops  (loops  within  loops)  in  BASIC. 

2000  LDX  #$0A  Start  of  first  loop. 

2002  LDY  #$0  Start  of  second  loop. 

2004  DEY 

2005  BNE  $2004  If  Y  isn't  yet  zero,  loop  back  to  DEcrease  Y 

again — this  is  the  inner  loop. 

2007  DEX  Reduce  the  outer  loop  by  one. 

2008  BNE    $2002     If  X  isn't  yet  zero,  go  through  the  entire  DEY 

loop  again. 
200 A  Continue  with  the  rest  of  the  program.... 

One  thing  to  watch  out  for:  Be  sure  that  a  loop  BNEs  back 
up  to  one  address  after  the  start  of  its  loop.  The  start  of  the 
loop  sets  a  number  into  a  register  and,  if  you  keep  looping  up 
to  it,  you'll  always  be  putting  the  same  number  into  it.  The 
DEcrement  (decrease  by  one)  instruction  would  then  never 
bring  it  down  to  zero  to  end  the  looping.  You'll  have  created 
an  endless  loop.  This  is  another  one  of  those  common  bugs. 
So  if  your  program  hangs  up,  check  to  see  if  you're  looping 
back  into  an  initialization  section. 

The  example  above  could  be  used  for  a  timing  loop  in  a 
r— <i  way  that's  similar  to  the  method  that  BASIC  creates  delays 

O  with  FOR  T  =  1  TO  2000:  NEXT  T.  Also,  sometimes  you  do 

want  to  create  a  pseudo-endless  loop  (the  BEGIN-UNTIL  in 

n  structured  programming).  A  useful  pseudo-endless  loop  in 

BASIC  waits  until  the  user  hits  any  key:  10  GET  K$:  IF  K$  - 
""  THEN  10. 
I— i  The  simplest  way  to  accomplish  this  in  ML  is  to  look  on 

•I    '  the  map  of  your  computer  to  find  which  byte  holds  the  last 

key  pressed  number.  On  the  128,  it's  $D4.  In  any  event,  when 
a  key  is  pressed,  it  deposits  its  special  numeric  value  into  this 
cell.  If  no  key  is  pressed,  $D4  contains  the  number  88.  How- 
ever, there's  a  built-in  ROM  routine  at  $FFE4  which  will  re- 
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turn  the  ASCII  value  of  a  keypress.  It's  often  easier  to  use  i    / 

than  polling  $D4  because  $D4  gives  character  values  in  the  ' — ' 

keyboard  matrix  code  which  differ  from  ASCII.  (To  find  out 
more  about  your  keyboard  input  options,  see  INPUT  and  GET 
in  Chapter  9.)  Here's  $FFE4  in  action: 

4000    JSR     $FFE4 

4003    BEQ    $4000  I    J 

Unless  a  key  is  being  pressed  on  the  keyboard,  a  JSR  to 
$FFE4  results  in  a  zero  result  (setting  the  Z  flag),  and  so  when 
we  test  the  Z  flag  with  BEQ,  we'll  keep  looping  back  to  ad- 
dress 4000  in  the  example  above  until  someone  presses  a  key. 
When  a  key  is  finally  pressed,  the  BEQ  test  will  then  fail  and 
we'll  fall  through  to  whatever  instruction  you  have  put  at  ad- 
dress $4005  right  below  the  BEQ.  At  this  point,  the  accumulator 
will  hold  the  ASCII  value  of  the  key  that  was  pressed. 

Dealing  with  Strings 

You've  probably  been  wondering  how  ML  handles  strings. 

It's  pretty  straightforward.  There  are  essentially  two  ways: 
known-length  and  zero-delimit.  If  you  know  how  many  char- 
acters there  are  in  a  message,  you  can  store  this  number  at  the 
very  start  of  the  text:  5ERROR.  (The  number  5  will  fit  into  one 
byte.)  If  this  message  is  stored  in  your  "message  zone" — some 
arbitrary  area  of  free  memory  set  aside  by  you  at  the  begin- 
ning to  hold  all  of  your  messages — you  would  make  a  note  of 
the  particular  address  of  the  "ERROR"  message.  Say  it's 
stored  at  address  $0FE6  (4070). 

To  print  out  the  message,  you  pluck  off  the  length  and 
then  repeatedly  JSR  to  $FFD2,  the  128's  character  output  rou- 
tine in  ROM.  But  remember  that  any  time  you  want  to  access  i     [ 
the  built-in  ROM  routines,  you  must  have  switched  in  bank  15  ' — ' 
by  LDA  #0:STA  $FF00. 

Alternatively,  you  could  simply  set  up  your  own  zero  •.     > 

page  pointers  to  the  screen  and  use  the  STA  (NN),Y  addressing  u_/ 

mode  (the  NN  means  "any  number"). 

Screen  memory  starts  at  $0400  (1024).  You  can  set  up  a  i    | 

"cursor  management"  system  for  yourself.  To  simplify,  we'll  I — '■■> 

send  our  message  to  the  beginning  of  the  128's  screen  and  just 
use  the  simple  absolute,Y  addressing  mode:  .    , 
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n2000    LDX  $0FE6      Remember,  we  put  the  length  of  the  message 
as  the  first  byte  of  the  message,  so  we  load  our 
counter  with  the  length. 
p— I  2003    LDY  #$0  Y  will  be  our  message  offset. 

I    J  2005    LDA  $0FE7,Y  Gets  the  character  at  the  address  plus  Y.  Y  is 

zero  the  first  time  through  the  loop,  so  the  "e" 
from  here  lands  in  the  accumulator.  It  also 
f~]  stays  in  $0FE7  (4071).  It's  just  being  copied 

into  the  accumulator. 
2008    STA  $0400,Y   We  can  make  Y  do  double-duty  as  the  mes- 
sage and  the  screen-printout  offset.  Y  is  still 
zero,  so  the  "e"  goes  to  $0400  the  first  time 
through  the  loop. 
200B    INY  Prepare  to  add  one  to  the  message-storage 

location  and  to  the  screen-print  location. 
200C   DEX  Lower  the  counter. 

200D  BNE  $2005       If  X  isn't  used  up  yet,  go  back  and  get-and- 
print  the  next  character,  the  "r." 

One  thing  you  should  remember  when  printing  to  the 
screen:  there  are  two  different  codes  you  can  use.  If  you  STA 
$0400  as  we  do  in  the  example  immediately  above,  you  are 
using  the  screen  POKE  code,  the  same  code  that  would  apply 
were  you  to  POKE  that  value  from  BASIC.  The  other  code 
(very  similar  to  standard  ASCII)  applies  when  you  load  the 
character  value  into  the  accumulator  and  then  JSR  $FFD2. 

When  you  turn  on  the  128,  its  default  mode  is  uppercase/ 
graphics.  You  can  change  it  to  uppercase/  lowercase  by  print- 
ing CHR$(14)— in  ML,  LDA  #14:JSR  $FFD2— and  back  to 
graphics  by  printing  CHR$(12).  Alternately,  you  can  switch 
between  modes  by  pressing  the  SHIFT  and  Commodore  keys 
simultaneously.  If,  when  you  are  testing  the  examples  below, 
j—)  you  are  getting  graphics  rather  than  letters  of  the  alphabet, 

'._.!  you  should  switch  to  the  uppercase/lowercase  screen  mode  as 

described.  Using  the  $FFD2  printing  routine,  however,  will 
r— »  work  as  expected  in  any  mode. 


H 
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If  the  Length  Is  Not  Known 

There  is  yet  another  way  to  print  to  the  screen — probably  the 
most  common  and  the  easiest,  and  it  doesn't  require  that  you 
know  the  length  of  the  string.  You  just  put  a  special  character 
(usually  zero)  at  the  end  of  each  message  to  show  its  limit. 
This  is  called  a  delimiter.  A  zero  works  well  because,  in  ASCII, 
the  value  zero  has  no  character  or  function  (such  as  a  carriage 

109 


Chapter  6 


u 
u 


u 


u 


return)  coded  to  it.  Consequently,  any  time  the  computer  loads 

a  zero  into  the  accumulator  (which  will  flip  up  the  Z  flag),  it 

will  then  know  that  it  is  at  the  end  of  your  message.  At 

$0FE6,  we  might  have  a  couple  of  error  messages:  "Ball  out  of  i    i 

rangeOTime  nearly  up!0".  (These  zeros  are  not  ASCII  zeros,  I — > 

remember.  ASCII  zero,  the  zero  character  that  can  be  printed, 

has  a  value  of  48.) 

To  print  the  time  warning  message  to  the  top  of  the 
screen: 

2000    LDY   #$0 

2002    LDA  $0FF8,Y  Get  the  "T." 

2005    BEQ   $2005       The  LDA  just  above  will  flip  the  zero  flag  up 

if  it  loads  a  zero,  so  we  forward  branch  out  of 

our  message-printing  loop. 
2007    STA   $0400,Y   We're  using  the  Y  as  a  double-duty  offset 

again. 
200A  INY 
200B    JMP    $2002       In  this  loop,  we  always  jump  back.  Our  exit 

from  the  loop  is  not  here,  at  the  end.  Rather,  it 

is  the  Branch  if  EQual  which  is  within  the 

loop.  This  is  similar  to  the  BEGIN-UNTIL 

structure  in  structured  programming. 
200E  Continue  with  another  part  of  the  program. 

Now  that  we  know  the  address  which  follows  the  loop 
($200E),  we  can  store  that  address  into  the  "false  forward 
branch"  we  left  in  address  $2006.  What  number  do  we  store 
into  $2006?  Just  subtract  $2007  from  $200E,  which  is  7. 

Of  these  two  ways  of  handling  strings,  the  zero-delimit 
method  is  the  most  popular  and  probably  the  easiest  to  use. 
It's  even  easier  if  you  use  LADS.  With  LADS,  you  don't  need 
to  remember  the  address  of  the  stored  string,  you  just  give 
each  string  a  label.  Also,  you  don't  need  to  translate  the  mes-  \\ 

sage  into  ASCII,  just  use  the  .BYTE  pseudo-op  in  LADS.  v*~- 

Here's  how  you  would  write  the  source  code  for  LADS  using 
the  zero-delimit  technique  example  above:  j    j 

100  SCREEN  =  1024  This  variable  is  defined  at  the  start  of  the  pro- 
gram, not  with  the  body  of  the  ML.  The  num- 
bers on  the  left  are  not  addresses;,  they  are  j 
line  numbers  that  you  use  when  writing  the  v~' 
source  code.  The  assembler  handles  memory 
addresses  for  you.  j     I 
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500  LDY  #0 

510  MESSAGE  LDA  TIMEOUT,Y         Get  the  "T." 

520  BEQ  MORE 

530  STA  SCREEN,  Y 

540  INY 

550  JMP  MESSAGE 

560  MORE         Continue  with  another  part  of  the  program. 


1000  TIMEOUT  .BYTE  "TIME 

NEARLY  UP!":  .BYTE  0      Message  stored  with  a  true  zero  at 

the  end.  This  is  stored  at  the  very 
end  of  the  ML  program,  not  in  with 
the  instructions  themselves. 

All  the  ways  of  handling  messages  discussed  above  are 
effective,  but  you  must  keep  a  list  on  paper  of  the  starting  ad- 
dresses of  each  message  if  you  are  using  the  monitor  assem- 
bler so  that  you  can  remember  from  where  to  pick  off  the 
letters  of  the  message.  In  ML,  you  have  the  responsibility  for 
some  of  the  tasks  that  BASIC  (at  an  expense  of  speed)  does  for 
you.  If  you're  using  LADS,  however,  you  can  simply  define 
the  location  of  the  message  with  a  label. 

Also,  when  using  these  techniques,  no  message  can  be 
larger  than  255  characters  because  the  offset  and  counter  reg- 
isters (X  and  Y)  can  count  only  that  high  before  starting  over 
at  zero  again.  To  print  two  strings  back- to-back  gives  a  longer, 
but  still  less  than  255-byte-long,  message: 

2000    LDY  #$0 
j_J  2002    LDX  #$2         In  this  example,  we  use  X  as  a  counter  which 

represents  the  number  of  messages  we  are 
printing. 
2004    LDA  $4000,Y   Get  the  "B"  from  "Ball  out  of...." 
2007    BEQ  $2011       Go  to  increment  Y,  reduce  (and  check)  the 
value  of  X. 
I— |  2009    STA  $0400,Y   We're  using  the  Y  as  a  double-duty  offset 

'     '  again. 

200D   INY 
200E    JMP   $2004 

2011    INY  We  need  to  raise  Y  since  we  skipped  that  step 

when  we  branched  out  of  the  loop. 
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2012  DEX                  At  the  end  of  the  first  message,  X  will  be  a  ,     , 

one;  at  the  end  of  the  second  message,  it  will  I I 

be  zero. 

2013  BNE  $2004       If  X  isn't  down  to  zero  yet,  reenter  the  loop  to 

print  out  the  second  message.  I     I 

This  example,  too,  could  not  deliver  a  message  longer 
than  255  characters.  To  fill  your  screen  with  instructions  in-  (    ( 

stantly  (say,  at  the  start  of  a  game),  you  can  use  the  following  1 | 

mass-move.  We'll  assume  that  the  instructions  go  from  $5000 
to  $6024  in  memory  and  that  you  want  to  transfer  them  to  the 
screen  (at  $0400): 

2000  LDY  #$0 

2002  LDA  $5000,Y 

2005  STA  $0400,Y 

2008  LDA  $5100,Y 

200B  STA  $0500,Y 

200E  LDA  $5200,Y 

2011  STA  $0600,Y 

2014  LDA  $5300,Y 
2017  STA  $0700,Y 
201A  INY 

201B    BNE  $2002       If  Y  hasn't  counted  up  to  0— which  comes  just 
above  255 — go  back  and  load-store  the  next 
character  in  each  quarter  of  the  large  message. 

This  technique  is  fast  and  easy  anytime  you  want  to 
mass-move  one  area  of  memory  to  another.  It  makes  a  copy 
and  does  not  disturb  the  original  memory.  To  mass-clear  a 
memory  zone  (to  clear  the  screen,  for  example),  you  can  use  a 
similar  loop,  but  instead  of  loading  the  accumulator  each  time 
with  a  different  character,  you  load  it  at  the  start  with  32,  the 
128's  code  for  the  character  that  prints  a  space: 

2000  LDA  #32  j! 

2002  LDY  #0 

2004  STA  $0400,  Y 

2007  STA  $0500,Y  I     I 

200A  STA  $0600,Y  L- J 

200D  STA  $0700,Y 

2011  INY 

2012  BNE  $2004 

Of  course  a  simpler  way  to  clear  the  screen  would  be  to 
JSR  to  the  PRINT  routine  in  BASIC  ROM  after  having  loaded  j    j 

the  clear-screen  character  into  the  accumulator:  LDA  #$93:JSR  1— 

$FFD2.  In  Chapter  7  we  will  explore  the  techniques  of  using 
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BASIC  as  a  group  of  examples  to  learn  from  and  also  as  a 
collection  of  ready-made  ML  subroutines.  Now,  though,  we 
can  look  at  how  subroutines  are  handled  in  ML. 

5.  The  Subroutine  and  Jump  Group: 
JMP,  JSR,  RTS 

JMP  has  only  one  useful  addressing  mode:  absolute.  You  give 
it  a  firm,  two-byte  argument  and  it  goes  there.  The  computer 
puts  the  argument  into  the  program  counter,  and  control  is 
transferred  to  this  new  address  where  an  instruction  located 
there  is  acted  upon.  (There  is  a  second  addressing  mode,  JMP 
indirect,  which  has  a  bug  and  is  best  left  unused.) 

JSR  can  use  only  absolute  addressing. 

RTS's  addressing  mode  is  implied.  The  address  is  on  the 
stack,  put  there  during  the  JSR. 

JSR  (Jump  to  SubRoutine)  is  the  same  as  GOSUB  in 
BASIC,  but  instead  of  giving  a  line  number,  you  give  an  ad- 
dress in  memory  where  the  subroutine  sits  (or,  with  LADS, 
you  give  a  label  name).  BASIC'S  SYS  is  a  kind  of  JSR,  too.  It 
acts  like  GOSUB,  except  the  destination  is  an  ML  routine 
rather  than  a  BASIC  subroutine. 

RTS  (ReTurn  from  Subroutine)  is  the  same  as  RETURN  in 
BASIC,  but  instead  of  returning  to  the  next  BASIC  command, 
you  return  to  the  address  following  the  JSR  instruction  (it's  a 
three-byte-long  instruction  containing  JSR  and  the  two-byte 
target  address).  JMP  (JuMP)  is  GOTO.  Again,  you  JMP  to  an 
address  or  label  name,  not  a  line  number.  As  in  BASIC,  there 
is  no  RETURN  from  a  JMP. 

Some  Further  Cautions  About  the  Stack 

)    |  The  stack  is  like  a  pile  of  coins.  The  last  one  you  put  on  top  of 

the  pile  is  the  first  one  you'll  pull  off  later.  The  main  reason 
that  the  8502  chip  sets  aside  an  entire  page  of  memory  for  the 

I     |  stack  is  that  it  has  to  know  where  to  go  back  to  after  GOSUBs 

and  JSRs. 

A  JSR  instruction  "pushes"  the  address  held  in  the  pro- 

i    J  gram  counter  plus  two  onto  the  stack  and,  later,  the  next  RTS 

"pulls"  the  top  two  numbers  off  the  stack,  increments  the  re- 
suit,  and  uses  this  number  as  its  argument  (target  address)  for 

™  the  return.  Some  programmers,  as  we  noted  before,  like  to 

play  with  the  stack  and  use  it  as  a  temporary  register  to  PHA 
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(PusH  Accumulator  onto  stack).  This  sort  of  thing  is  best  ,     , 

avoided  until  you  are  an  advanced  ML  programmer.  Stack  i I 

manipulations  often  result  in  a  very  confusing  program.  Han- 
dling the  stack  is  one  of  the  few  things  that  the  computer  does 
for  you  in  ML.  Let  it.  I | 

The  main  function  of  the  stack  (as  far  as  we're  concerned) 
is  to  hold  return  addresses.  It's  done  automatically  for  us  by  ,  - , 

"pushes"  with  the  JSR  and,  later,  "pulls"  (sometimes  called  ! ( 

pops)  with  the  RTS  instruction.  If  we  don't  bother  the  stack,  it 
will  serve  us  well.  There  are  thousands  upon  thousands  of 
cells  where  you  could  temporarily  leave  the  accumulator — or 
any  other  value — without  fouling  up  the  orderly  arrangement 
of  your  return  addresses. 

Subroutines  are  extremely  important  to  ML  programming. 

ML  programs  are  designed  around  them,  as  we'll  see. 
There  are  times  when  you'll  be  several  subroutines  deep  (one 
will  call  another  which  calls  another);  this  is  not  as  confusing 
as  it  sounds.  Your  main  player-input  routine  might  call  a 
print-message  subroutine  which  itself  calls  a  wait-until-key-is- 
pressed  subroutine.  If  any  of  these  routines  PHA  (PusH  the 
Accumulator  onto  the  stack),  they  then  disturb  the  addresses 
on  the  stack.  If  the  extra  number  on  top  of  the  stack  isn't 
PLAed  off  (PulL  Accumulator),  the  next  RTS  will  pull  off  the 
number  that  was  PHAed  along  with  half  the  correct  address.  It 
will  then  merrily  return  to  what  it  thinks  is  the  correct  ad- 
dress: It  might  land  somewhere  in  the  RAM,  it  might  go  to  an 
address  somewhere  in  the  outer  reaches  of  your  operating  sys- 
tem— but  it  certainly  won't  go  where  it  should. 

Some  programmers  like  to  change  a  GOSUB  into  a  GOTO 
(in  the  middle  of  the  action  of  a  program)  by  PLA  PLA.  Pull- 
ing the  two  top  stack  values  off  with  PLA  PLA  has  the  effect  . 

of  eliminating  the  most  recently  stored  RTS  address.  It  does  i ( 

leave  a  clean  stack,  but  why  bother  to  JSR  in  the  first  place  if 

you  later  want  to  change  it  to  a  GOTO?  Why  not  use  JMP  in  k 

the  first  place.  (There  is  some  use  for  this  technique,  but  it's  j | 

for  advanced  ML  programming  where  you  want  to  speed  up  a 

program  by  returning  directly  to  some  routine  elsewhere  in 

the  calling  subprogram.  LADS  uses  this  method  in  places.)  ] | 

There  are  cases,  too,  when  the  stack  has  been  used  to 
hold  the  current  condition  of  the  flags  (the  status  register 
byte).  '  U 
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r-j  This  is  pushed/pulled  from  the  stack  with  PHP  and  PLP. 

'    '  You  probably  never  will,  but  if  you  should  need  to  "remem- 

ber" the  condition  of  the  status  flags,  why  not  just  PHP  PLA 

r— i  STA  $NN  (NN  means  the  address  is  your  choice)?  Set  aside  a 

byte  somewhere  that  can  hold  the  flags  (they  are  always 
changing  inside  the  status  register  during  a  program  run)  for 
later  and  keep  the  stack  clean.  Leave  stack  acrobatics  to  Forth 
programmers.  The  stack,  except  for  advanced  ML,  should  be 
inviolate. 

Forth,  an  interesting  language,  requires  frequent  stack 
manipulations.  But  in  the  Forth  environment,  the  reasons  for 
this  and  its  protocol  make  excellent  sense.  In  ML,  though, 
stack  manipulations  are  a  sticky  business. 

Saving  the  Current  Environment 

There  are  two  exceptions  to  our  leave-the-stack-alone  rule. 
Sometimes  (especially  when  you  are  "borrowing"  a  routine 
from  BASIC  by  JSRing  into  the  ROM)  you  will  want  to  take 
up  with  your  own  program  from  where  it  left  off.  In  other 
words,  you  want  to  preserve  what's  in  the  registers. 

However,  when  you  JSR  into  one  of  these  ready-made 
subroutines,  you  often  don't  know  what  sorts  of  things  the 
subroutine  will  do  to  your  accumulator  or  X  and  Y  registers. 
To  illustrate,  let's  say  you  are  going  to  open  a  disk  file  and 
you've  written  the  necessary  subroutine  and  labeled  it  OPEN. 
You  will  JSR  to  OPEN  and  it  will  have  to  JSR,  in  turn,  several 
times  into  the  ROM  to  accomplish  the  job  of  opening  a  disk 
file.  However,  you  need  to  retain  the  status  of  the  registers  be- 
cause your  program  is  going  to  need  them.  You  sometimes 
cannot  afford  to  have  unpredictable  things  happen  to  your  X, 
Y,  A,  and  status  registers.  If  you  know  you  don't  need  to  pre- 
serve the  state  of  the  accumulator  or  the  X  or  Y  register,  then 
JSR  blithely  away.  The  JSR  into  ROM  will  probably  change 
the  registers,  but  you  don't  care. 

However,  sometimes  you  are  using,  let's  say,  Y  to  hold 
the  offset  of  a  line  of  information  or  a  screen  line.  You  can't 
allow  it  to  suffer  from  some  unknown  event  in  a  ROM  sub- 
routine. In  such  cases,  you  can  use  the  following  "save  the 
state  of  things"  routine: 

2000  PHP  Push  the  status  register  onto  the  stack. 

2001  PHA 

2002  TXA 
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2003  PHA  ( 

2004  TYA  [J 

2005  PHA 

2006  JSR    OPEN   To  the  various  ROM  calls  necessary  to  open  a 

file  that  you've  written  as  a  subroutine  called  j     • 

"OPEN."  When  the  subroutine  is  finished,  it  — ' 

will  end  with  an  RTS.  This  RTS  will  remove  the 
return  address  ($2009)  from  the  stack,  and  \    ) 

you'll  then  have  access  to  a  mirror  image  of  the  ' — ' 

things  you  had  pushed  onto  the  stack.  They  are 
pulled  out  in  reverse  order,  as  you  can  see  be- 
low. This  is  because  the  first  pull  from  the  stack 
will  get  the  most  recently  pushed  number.  If  you 
make  a  little  stack  of  coins,  the  first  one  you  pull 
off  will  be  the  last  one  you  put  onto  the  stack. 

2009    PLA  Now  we  reverse  the  order  to  get  them  back. 

200A  TAY 

200B    PLA 

200C   TAX 

200D  PLA  This  one  stays  in  A. 

200E    PLP  The  status  register. 

This  example  demonstrates  how  to  save  the  registers,  JSR 
to  a  subroutine  where  unpredictable  things  will  happen  to  the 
registers,  and  then  restore  the  registers  to  their  previous  state. 
It  preserves  everything,  including  the  flags  (PHP,  push  proces- 
sor status  register)  as  it  was  before  you  JSRed.  Use  this  tech- 
nique when  you're  unsure.  Nearly  every  ROM  routine  mentioned 
in  this  book  will  alter  one  or  more  of  the  registers.  The  only 
truly  safe  one  is  JSR  $FFD2,  the  output-a-character  routine. 
You  can  use  this  one  with  impunity. 

Saving  the  current  state  of  things  before  visiting  an  un- 
charted, unpredictable  subroutine  is  probably  the  only  valid 
excuse  for  playing  with  the  stack  as  a  beginner  in  ML.  The  j    / 

routine  above  is  constructed  to  leave  the  stack  intact.  Every- 
thing that  was  pushed  on  has  been  pulled  back  off. 

If  you  dare,  you  can  also  use  the  stack  as  a  temporary  I    I 

storage  place  when  you  need  to  save  something  briefly.  You 
could  save  the  accumulator  (while  JSRing  to  the  GET  routine 
in  BASIC)  by  PHA:JSR  $FFE4:PLA.  That  would  temporarily  )    I 

push  the  accumulator  onto  the  stack,  hold  it  there  beneath  the  — 

two-byte  return  address  pushed  onto  the  stack  by  the  JSR,  and 
then  pull  it  off  again  after  the  RTS  had  fetched  the  return  ad-  j    I 

dress  (leaving  your  accumulator  on  top  of  the  stack).  This  *-— ' 
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pushing  is  sometimes  considered  a  dangerous  practice  be- 
cause, if  you  forget  to  match  every  push  with  a  subsequent 
pull,  the  stack  will  overflow  and  you  might  not  realize  why. 
Use  this  trick  at  your  own  risk.  For  simple  register  saves,  it's 
pretty  easy  to  define  register  "holding  bytes"  using  LADS  and 
then  stuff  things  there  whenever  you  need  temporary  storage: 

10  GET  =  $FFE4 

100  STY  Y:STA  A:LOOP  JSR  GET:BEQ  LOOP:LDA  A:LDY  Y 

While,  somewhere  after  the  end  of  your  program  proper, 
down  with  the  messages  and  other  things  that  are  data,  not 
program,  you  have: 

5000  A  .BYTE  0 
5010  Y  .BYTE  0 
5020  X  .BYTE  0 

The  Significance  of  Subroutines 

Possibly  the  best  way  to  approach  ML  program  writing — es- 
pecially a  large  program — is  to  think  of  it  as  a  collection  of 
subroutines.  Each  of  these  subroutines  should  be  small.  It 
should  be  listed  on  a  piece  of  paper  followed  by  a  note  on 
what  it  needs  as  input  and  what  it  gives  back  as  parameters. 
"Parameter  passing"  simply  means  that  a  subroutine  needs  to 
know  things  from  the  main  program  (parameters)  which  are 
handed  to  it  (passed)  in  some  way.  Alternatively,  if  you  are 
using  LADS,  you  can  insert  comments  about  parameters  into 
the  body  of  the  source  code  of  the  program  using  the  semi- 
colon (;)  remark  pseudo-op. 

The  current  position  of  the  record  in  a  database  is  a 
parameter  which  has  its  own  "register"  (we  would  have  set 
aside  a  register  for  it  at  the  start  when  we  were  assigning 
memory  space  either  on  paper  for  simple  assemblers  or  by 
using  the  equate  pseudo-op  for  LADS).  So,  the  "look  at  the 
next  record  in  the  database"  subroutine  is  a  double-adder 
which  adds  40  or  whatever  to  the  "current  position  register." 
This  value  always  sits  in  the  register  to  be  used  anytime  any 
subroutine  needs  this  information.  In  other  words,  the  register 
(we  called  it  FINGER  in  a  previous  example)  is  always  point- 
ing to  our  current  position  within  the  database.  This  is  why 
such  registers  are  called  pointers. 

The  "look  at  the  next  register"  subroutine  sends  the 
current-position  parameter  by  passing  it  to  the  current-position 

register. 
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This  is  one  example  of  a  way  that  parameters  are  passed.  ,    ) 

Another  example  might  be  when  you  are  telling  a  delay  loop  I j 

how  long  to  delay.  Ideally,  your  delay  subroutine  will  be 

multipurpose.  That  is,  it  can  delay  for  anywhere  from  1/2  sec-  ,     , 

ond  to  60  seconds  or  something.  This  means  that  the  sub-  I ) 

routine  itself  isn't  locked  into  a  particular  length  of  delay. 

The  main  program  will  "pass"  the  amount  of  delay  to  the  v    . 

subroutine.  ( i 

3000    LDY  #$0 

3002  INY 

3003  BNE  $3002 

3005  DEX 

3006  BNE  $3000 
3008    RTS 

Notice  that  X  never  is  initialized  (set  up)  here  with  any 
particular  value.  This  is  because  the  value  of  X  is  passed  to 
this  subroutine  from  the  main  program.  If  you  want  a  short 
delay,  you  would: 

2000    LDX  #$5 
2002    JSR    $3000 

And  for  a  delay  which  is  twice  as  long  as  that: 

2000    LDX  #$0A  10  decimal 
2002    JSR    $3000 

In  some  ways,  the  less  a  subroutine  does,  the  better.  If  it's 
not  entirely  self-sufficient,  and  the  shorter  and  simpler  it  is, 
the  more  versatile  it  will  be.  For  example,  our  delay  above 
could  function  to  time  responses,  to  hold  sounds  for  specific 
durations,  and  so  on.  When  you  make  remarks  about  a  gen- 
eral-purpose routine,  write  something  like  this:  3000  ;  DELAY 
LOOP  (expects  duration  in  X;  returns  zero  in  X).  K    . 

The  longest  duration  delay  would  be  set  up  with  LDX  #0.  I 1 

This  is  because  the  first  thing  that  happens  to  X  in  the  delay 
subroutine  is  DEX.  If  you  DEX  a  zero,  you  get  255.  If  you  , 

need  longer  delays  than  the  maximum  value  of  X,  simply:  | | 

2000    LDX  #$0 

2002    JSR    $3000  ,     . 

2005    JSR    $3000     Notice  that  we  don't  need  to  set  X  to  zero  this  L_J 

second  time.  It  returns  from  the  subroutine  with 

a  zeroed  X. 

You  could  even  make  a  loop  out  of  the  JSRs  above  for  ex- 
tremely long  delays.  The  point  to  notice  here  is  that  it  helps  to 
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document  each  subroutine  in  your  library:  what  parameters  it 
expects;  what  registers,  flags,  and  so  on,  it  changes;  and  what 
it  leaves  behind  as  a  result.  This  documentation — on  a  single 
j~"j  sheet  of  paper  or  within  LADS  source — helps  you  remember 

each  routine's  address  and  lets  you  know  what  effects  and 
preconditions  are  involved. 

H  JMP 

Like  BASIC'S  GOTO,  JMP  is  easy  to  understand.  It  goes  to  an 
address:  JMP  $5000  leaps  from  wherever  it  is  to  start  carrying 
out  the  instructions  which  start  at  $5000.  It  doesn't  affect  any 
flags.  It  doesn't  do  anything  to  the  stack.  It's  clean  and  simple. 
Yet  some  advocates  of  structured  programming  suggest  avoid- 
ing JMP  (and  GOTO).  Their  reasoning  is  that  JMP  is  a  shortcut 
and  a  poor  programming  habit. 

For  one  thing,  they  argue,  using  GOTO  makes  programs 
confusing.  If  you  drew  lines  to  show  a  program's  "flow"  (the 
order  in  which  instructions  are  carried  out),  a  program  with 
lots  of  GOTOs  would  look  like  boiled  spaghetti.  Many  pro- 
grammers feel,  however,  that  JMP  has  its  uses.  Clearly,  you 
should  not  overdo  it  and  lean  heavily  on  JMP.  In  fact,  you 
might  see  if  there  isn't  a  better  way  to  accomplish  something 
if  you  find  yourself  using  it  all  the  time  and  your  programs  are 
becoming  impossibly  awkward.  But  JMP  is  convenient,  often 
necessary,  in  ML. 

An  8502  Chip  Bug 

On  the  other  hand,  there  is  another,  rather  peculiar  JMP 
addressing  mode  which  is  hardly,  if  ever,  used  in  ML:  JMP 
($5000).  This  is  an  indirect  jump  which  works  like  the  indirect 
r— >  addressing  we've  seen  before.  Remember  that  with  the 

'     *  indirect,Y  addressing  mode,  LDA  ($81), Y,  the  number  in  Y  is 

added  to  the  address  found  in  $81  and  $82.  This  address  is  the 
r— )  real  place  we  are  LDAing  from,  sometimes  called  the  effective 

'     I  address.  If  $81  holds  a  00,  $82  holds  a  $40,  and  Y  holds  a  2, 

the  address  we  LDA  from  is  going  to  be  $4002.  Similarly  (but 
j— i  without  adding  Y),  the  effective  address  found  at  the  two 

'    i  bytes  within  the  parentheses  becomes  the  place  we  JMP  to  in 

JMP  ($5000). 

n  There  are  no  necessary  uses  for  this  instruction.  Best 

avoid  it  the  same  way  you  avoid  playing  around  with  the 
stack  until  you're  an  ML  expert.  If  you  find  it  in  your  comput- 
i— i 
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er's  BASIC  code,  it  will  probably  be  involved  in  an  "indirect  i     i 

jump  table,"  a  series  of  registers  which  are  dynamic.  That  is,  ' — > 

they  can  be  changed  as  the  program  progresses.  Such  a  tech- 
nique is  very  close  to  a  self -altering  program  and  would  have  i    > 
few  applications  in  ML.  But  worse  than  than,  there  is  a  bug  in  ' — ' 
the  8502  chip  itself  which  causes  the  indirect  JMP  instruction 
to  malfunction  under  certain  circumstances.  Just  put  JMP                     .    > 
($NNNN)  into  the  same  category  as  BPL  and  BMI.  Avoid  them.             1 — I 

If  you  decide  that  for  some  reason  you  must  use  indirect 
JMP,  be  sure  to  avoid  the  edge  of  pages,  such  as  JMP  ($NNFF). 
Whenever  the  low  byte  is  right  on  the  edge  of  a  page  ($FF  is 
on  the  edge,  it's  ready  to  reset  to  $00),  an  indirect  JMP  will 
correctly  use  the  low  byte  (LSB)  from  the  pointer  at  $NNF¥, 
but  it  will  not  pick  up  the  high  byte  (MSB)  from  $NNFF+1  as 
it  should.  Instead,  it  gets  the  high  byte  from  $NN00. 

Here's  how  this  error  would  work  if  you  had  set  up  a 
pointer  to  address  $5043  with  the  pointer  located  at  $40FF: 

$40FF  43 
$4100    50 

Your  intention  would  be  to  JMP  to  $5043  by  bouncing  off 
this  pointer.  You  would  write  JMP  ($40FF)  and  expect  that  the 
next  instruction  the  computer  would  follow  would  be  the 
instruction  located  at  $5043.  Unfortunately,  your  pointer 
would  malfunction  in  this  example.  You  would  land  at  $0043 
(if  address  $4000  held  a  zero).  The  indirect  JMP  would  get  its 
MSB  from  $4000. 

This  bug  does  not  apply  to  any  other  addressing  modes, 
just  JMP  (indirect).  So,  unless  you  want  to  take  a  chance  with  an 
addressing  mode  that's  strictly  for  advanced  programmers,  con- 
tains a  bug,  and  has  no  compelling  uses,  avoid  JMP  (indirect). 


U 
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6.  Debuggers: 
BRK  and  NOP 

BRK  and  NOP  have  no  arguments  and  are  therefore  members 
of  that  class  of  instructions  which  use  only  the  implied 
addressing  mode.  They  also  affect  no  flags  in  any  way  with  j  | 
which  we  would  be  concerned.  BRK  does  affect  the  I  and  B  ' — ' 
flags,  but  since  it  is  a  rare  situation  which  would  require  test- 
ing those  flags,  we  can  ignore  this  flag  activity  altogether.  i  j 
After  you've  assembled  your  program  and  it  doesn't  work  ' — ' 
as  expected  (few  do),  you  start  debugging.  Some  studies  have 
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shown  that  debugging  takes  up  more  than  50  percent  of  pro- 
gramming time.  Such  surveys  can  be  misleading,  however,  be- 
cause "making  improvements  and  adding  options"  frequently 
take  place  after  a  program  is  allegedly  finished  and  would  be 
thereby  categorized  as  part  of  the  debugging  process. 

Another  factor  is  that  these  surveys  reflect  the  sometimes 
inefficient  programming  styles  adopted  by  professional  or  aca- 
demic programming  teams.  Some  assemblers  and  compilers 
used  by  professionals  are  extraordinarily  cumbersome,  requir- 
ing heroic  efforts  with  linkers,  maps,  variable  definition,  and 
so  forth,  before  a  piece  of  program  can  be  tested.  LADS,  by 
contrast,  is  virtually  instantaneous.  It  will  make  the  process  of 
debugging  very  efficient. 

In  ML,  debugging  is  facilitated  by  setting  breakpoints  with 
BRK  and  then  seeing  what's  happening  in  the  registers  or 
memory.  If  you  insert  a  BRK,  it  has  the  effect  of  halting  the 
program  and  throwing  you  into  the  monitor  where  you  can 
examine,  say,  the  Y  register  to  see  if  it  contains  what  you 
would  expect  it  to  at  this  point  in  the  program.  It's  similar  to 
BASIC'S  STOP  instruction: 

2000    LDA  #$15 

2002  TAY 

2003  BRK 

At  this  point,  you  could  use  the  monitor  to  examine  any 
areas  of  memory  just  as  you  would  examine  variables  after 
having  your  BASIC  program  STOP. 

Debugging  Methods 

In  practice,  you  debug  whenever  your  program  runs  merrily 
along  and  then  does  something  unexpected.  It  might  crash  and 
lock  you  out.  You  look  for  a  likely  place  where  you  think  it  is 
failing  and  just  insert  a  BRK  right  over  some  other  instruction. 

Remember  that  when  you're  in  the  monitor  mode,  you  can 
directly  change  bytes,  you  can  insert  $00  (BRK)  where  you  want. 

In  the  example  above,  imagine  that  we  put  the  BRK  over 
a  STY  $8000.  Make  a  note  of  the  instruction  you  covered  over 
with  the  BRK  so  that  you  can  restore  it  later.  After  checking 
the  registers  and  memory,  you  might  find  something  wrong, 
some  variable  or  register  isn't  behaving  as  it  should  or  you 
somehow  never  even  arrive  at  the  break  (some  branch  or  JMP 
is  being  incorrectly  activated).  Now  you  have  narrowed  things 
down.  Now  you  can  locate  and  fix  the  error. 
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Sometimes  it  helps  to  have  a  printed  listing  of  the  suspect  i    t 

area  in  a  program.  You  can  turn  your  printer  on  and  off  with  I — ) 

the  .P  and  .NP  options  in  LADS,  printing  out  only  the  suspect 
zone  of  the  program  and  use  that  to  help  you  locate  errors  \    > 

while  working  with  the  monitor.  Alternatively,  you  can  check  ' — > 

the  program  with  the  built-in  disassembler. 

If  nothing  seems  wrong  at  this  point,  restore  the  original  i    i 

STY  over  the  BRK,  and  put  BRK  in  somewhere  further  on.  By  I — I 

this  process,  you  can  isolate  the  cause  of  the  oddity  in  your 
program.  Setting  breakpoints  (like  putting  STOP  into  BASIC 
programs)  is  an  effective  way  to  run  part  of  a  program  and 
then  examine  the  variables. 

Like  BRK  ($00),  the  hex  number  of  NOP  ($EA)  is  worth 
memorizing.  If  you're  working  within  your  monitor,  you  will 
need  to  use  hex  numbers,  and  these  two  are  particularly  worth 
knowing.  / 

NOP  means  NO  oPeration.  The  computer  slides  over 
NOPs  without  taking  any  action  other  than  increasing  the  pro- 
gram counter.  There  are  two  ways  in  which  NOP  can  be  effec- 
tively used. 

First,  it  can  be  an  eraser.  If  you  suspect  that  JSR  $8000  is 
causing  all  the  trouble,  try  running  your  program  with  every- 
thing else  the  same,  but  with  JSR  $8000  erased.  Simply  put 
three  $EAs  over  the  instruction  and  argument.  (Make  a  note, 
though,  of  what  was  under  the  $EAs  so  that  you  can  restore 
it.)  Then,  the  program  will  run  without  this  instruction,  with- 
out going  to  that  subroutine  at  $8000,  and  you  can  watch  the 
effects. 

Second,  it  is  sometimes  useful  to  use  $EA  to  hold  open 
some  space  temporarily.  If  you  don't  know  something  (an  ad- 
dress, a  graphics  value)  during  assembly,  $EA  can  mark  that  ,    , 

this  space  needs  to  be  filled  in  later  before  the  program  is  run.  I 1 

As  an  instruction,  it  will  let  the  program  slide  by.  $EA  could 

become  your  "fill  this  in"  alert  within  programs  in  the  way  ,     , 

that  we  use  self-branching  (leaving  a  zero)  to  show  that  we  1 i 

need  to  put  in  a  forward  branch's  address  when  using  a  mini- 
assembler. ,    j 

Less  Common  Instructions 

The  following  instructions  are  not  often  necessary  for  begin-  .    . 

ning  applications,  but  we  can  briefly  touch  on  their  main  uses.  i ) 

There  are  several  logical  instructions  which  can  manipulate  or 
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J""?  test  individual  bits  within  each  byte.  This  is  most  often  nec- 

essary when  interfacing.  If  you  need  to  test  what's  coming  in 
from  a  disk  drive,  or  translate  on  a  bit-by-bit  level  for  I/O 
P"j  (input/ output),  you  might  work  with  the  logical  group. 

In  general,  I/O  is  handled  for  you  by  your  machine's 
operating  system  and  is  well  beyond  beginning  ML  program- 
j"~j  ming.  I/O  is  perhaps  the  most  difficult,  or  at  least  the  most 

complicated,  aspect  of  ML  programming.  When  putting  things 
on  the  screen,  programming  is  fairly  straightforward,  but  han- 
dling the  data  stream  into  and  out  of  a  disk  is  pretty  involved. 
Timing  must  be  precise,  and  the  preconditions  which  need  to 
be  established  are  complex. 

For  example,  if  you  need  to  mask  a  byte  by  changing 
some  of  its  bits  to  zero,  you  can  use  the  AND  instruction. 
After  an  AND,  both  numbers  must  have  contained  a  one  in 
any  particular  bit  position  for  it  to  result  in  a  one  in  the  an- 
swer. This  lets  you  set  up  a  mask:  00001111  will  zero  any  bits 
within  the  left  four  positions.  So,  00001111  and  11001100  re- 
sult in  00001100. 

The  unmasked  bits  remained  unchanged,  but  the  four 
high  bits  were  all  masked  and,  thus,  zeroed. 

There  is  a  minor  use  for  AND  when  you  want  to  change 
a  character  to  a  reverse  (black  on  white)  or  change  it  back  to 
normal.  The  reversed  letter  A,  for  example,  has  a  value  of  $C1 
which  looks  like  this  in  binary  (all  the  bits  within  the  byte 
showing):  11000001.  Notice  that  the  left  two  bits  are  "on."  To 
change  this  to  a  normal  A  character,  we  need  to  turn  the 
leftmost  bit  off  so  that  we  end  up  with  01000001,  which  is 
$41.  You  can  turn  off  the  leftmost  bit  by  11000001  AND 
01111111,  which  will  leave  01000001.  When  this  is  expressed 
r— j  in  hex  numbers,  you  take  the  reversed  A  ($C1)  and  AND  it 

'    l  with  01111111  ($7F)  to  get  the  normal  $41.  Likewise,  reversed 

B  ($C2)  AND  $7F  results  in  a  normal  B  ($42). 
f-^  Going  the  other  way,  you  can  change  a  normal  A  into  a 

'    '  reversed  A  by  $41  ORA  $80  (10000000).  The  ORA  instruction 

is  the  same  as  AND,  except  it  lets  you  mask  to  set  bits  (make 
them  a  one).  Thus,  11110000  ORA  11001100  results  in 
11111100.  The  accumulator  will  hold  the  results  when  these 
instructions  are  used. 

EOR  (Exclusive  OR)  permits  you  to  toggle  bits.  Toggle 
means  to  switch  back  and  forth  between  two  states,  like  tog- 
gling a  light  switch  on  and  off.  If  a  bit  is  1,  it  will  go  to  0.  If 
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AND 

OR 

EOR 

0  AND  0  =  0 

0  OR  0  =  0 

0  EOR  0  =  0 

0  AND  1  =  0 

0  OR  1  =  1 

0  EOR  1  =  1 

1  AND  0  =  0 

1  OR  0  =  1 

1  EOR  0  =  1 

1  AND  1  =  1 

1  OR  1  =  1 

1  EOR  1  =  0 

u 
u 


it's  0,  it  will  flip  to  1.  EOR  is  sometimes  useful  in  games.  If  \    I 

you  are  heading  in  one  direction,  for  example,  and  you  want  ' — ' 

to  go  back  when  bouncing  a  ball  off  a  wall,  you  could  toggle. 

Let's  say  that  you  use  a  register  to  show  direction:  When  the  j    j 

ball's  going  up,  the  byte  contains  the  number  1  (00000001),  ' — ' 

but  down  is  0  (00000000).  To  toggle  this  least  significant  bit, 

you  would  EOR  with  00000001.  This  would  flip  1  to  0,  and  0  j    j 

to  1.  This  action  results  in  the  complement  of  a  number.  Thus,  ' — ' 

11111111  EOR  11001100  results  in  00110011. 

To  know  the  effects  of  these  logical  operators,  we  can 
look  them  up  in  truth  tables  which  give  the  results  of  all  pos- 
sible combinations  of  zeros  and  ones: 


Another  instruction,  BIT,  also  tests  (it  does  an  AND),  but, 
like  the  BNE,  and  so  forth,  branch  instructions,  it  does  not  af- 
fect the  number  in  the  accumulator — its  sole  purpose  is  to  set 
flags  in  the  status  register.  The  N  flag  is  set  (has  a  one)  if  bit  7 
has  a  one  (and  vice  versa).  The  V  flag  responds  similarly  to 
whatever  value  is  in  the  sixth  bit  of  the  tested  byte.  The  Z  flag 
shows  whether  or  not  the  result  of  the  AND  resulted  in  a 
zero.  Instructions,  like  BIT,  which  do  not  affect  the  numbers 
being  tested  are  called  nondestructive. 

We  discussed  LSR  and  ASL  in  the  chapter  on  arithmetic: 
They  can  conveniently  divide  and  multiply  by  two.  ROL  and 
ROR  rotate  the  bits  left  or  right  in  a  byte,  but,  unlike  with  the 
Logical  Shift  Right  or  Arithmetic  Shift  Left,  no  bits  are  lost  off 
one  end  during  the  shift.  ROL  will  leave  the  seventh  (most  \    | 

significant)  bit  in  the  carry  flag,  leave  the  carry  flag  in  the  ' — ' 

zeroth  bit  (least  significant  bit),  and  move  every  other  bit  one 
space  to  the  left:  I    I 

ROL    11001100   With  the  carry  flag  set,  results  in:  "~~" 

10011001    Carry  is  still  set;  it  got  the  leftmost  one. 

If  you  disassemble  your  computer's  BASIC,  you  may  well  j \ 

look  in  vain  for  an  example  of  ROL,  but  it  and  ROR  are  avail- 
able in  the  8502  instruction  set  if  you  should  ever  find  a  use  . 

for  them.  1 • 

Should  you  go  into  advanced  ML  arithmetic,  ROL  and 
ROR  can  be  used  for  multiplication  and  division  routines. 
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r"1  Please  see  Appendix  A  for  more  details  on  some  of  these  ob- 

scure instructions  if  you're  interested. 

Three  other  instructions  remain  to  be  discussed:  SEI  (SEt 
PI  Interrupt),  RTI  (ReTurn  from  Interrupt),  and  CLI  (CLear  Inter- 

rupt). These  operations  are  also  beyond  the  scope  of  a  book 
on  beginning  ML  programming,  but  we'll  briefly  note  their  ef- 
r*l  fects.  Your  computer  gets  busy  as  soon  as  the  power  goes  on. 

Things  are  always  happening:  Timing  registers  are  being  up- 
dated; the  keyboard,  the  video,  and  the  peripheral  connectors 
are  being  refreshed  or  examined  for  signals.  To  interrupt  all 
this  activity,  you  can  SEI,  perform  some  task,  and  then  CLI  to 
let  things  pick  up  where  they  left  off. 

SEI  sets  the  interrupt  flag.  Following  this,  all  maskable 
interruptions  (things  which  can  be  blocked  from  interrupting 
when  the  interrupt  status  flag  is  up)  are  no  longer  possible. 

There  are  also  nonmaskable  interrupts  which,  as  you  might 
guess,  will  jump  in  anytime,  ignoring  the  status  register. 

The  RTI  instruction  (ReTurn  from  Interrupt)  restores  the 
program  counter  and  status  register  (takes  them  from  the 
stack),  but  the  X  and  Y  registers,  and  so  on,  might  have  been 
changed  during  the  interrupt.  Recall  that  our  discussion  of  the 
BRK  instruction  involved  the  above  actions.  The  key  difference 
is  that  BRK  stores  the  program  counter  plus  two  on  the  stack 
and  sets  the  B  flag  on  the  status  register.  CLI  puts  the  inter- 
rupt flag  down  and  lets  all  interrupts  take  place. 

If  these  last  instructions  are  confusing  to  you,  it  doesn't 
matter.  They  are  essentially  hardware  and  interface  related. 

You  can  do  nearly  everything  you  will  want  to  do  in  ML 
without  them.  How  often  have  you  used  WAIT  in  BASIC? 


n 


i   \ 


A  Newer  Chip 

The  venerable  6502  chip,  which  has  been  the  brains  of  most 
of  the  popular  home  computers  for  years,  has  been  replaced  in 
p")  the  128  by  the  8502.  From  a  programmer's  point  of  view, 

there's  no  difference  between  the  two. 

Commodore  owns  the  manufacturer  of  the  6502  and  its 
newer  cousins.  When  the  64  was  built,  they  decided  to  make  a 
few  changes  to  the  6502  and  called  it  the  6510.  Similarly,  a 
few  more  changes  resulted  in  the  8502  inside  the  128.  These 
chips  are  physically  different — they  are  not  pin-compatible. 
This  means  you  cannot  pull  a  6502  out  of  a  socket  and  plug 
an  8502  in  its  place,  because  the  operating  signals  appear  on 
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different  pins.  (If  you're  interested,  the  data  bus  is  pins  30-37  j    / 

on  a  6510,  but  pins  26-33  on  a  6502.  The  6510  is  a  6502  with  <— j 

an  on-chip  six-bit  I/O  port  addressed  at  locations  0000  and 
0001.  The  8502  is  an  enhanced  6510,  capable  of  operating  at  2  \    j 

megahertz  and  with  a  seven-bit  I/O  port.)  * — > 

For  programmers,  though,  the  significant  thing  is  that 
none  of  the  physical  differences  reflect  any  modifications  to  j    ; 

the  instruction  set,  the  commands  we've  been  learning  in  this  ' — ' 

chapter.  From  a  programmer's  perspective,  the  three  processors 
used  in  the  Commodore  machines  are  identical. 

In  any  event,  we've  covered  all  the  instructions  now.  It's 
time  to  explore  some  important  shortcuts.  Life  would  be  far 
tougher  for  ML  programmers  if  they  had  to  write,  for  example, 
the  entire  complex  of  instructions  necessary  to  communicate 
with  the  disk  drive.  Fortunately,  we  can  turn  jobs  like  that 
over  to  the  ML  routines  already  written,  already  inside  BASIC. 
That's  the  subject  of  the  next  chapter. 
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Borrowing  from  BASIC 


BASIC  is  a  collection  of  ML  subroutines.  It  is  a  large  web  of 
hundreds  of  short  ML  programs.  Why  not  use  some  of  them 
]~""j  by  JSRing  to  them?  At  times,  this  is  in  fact  the  best  solution  to 

a  problem. 

How  would  this  differ  from  BASIC  itself?  Doesn't  BASIC 
just  create  a  series  of  JSRs  when  it  runs?  Wouldn't  using  BA- 
SIC'S ML  routines  in  this  way  be  just  as  slow  as  BASIC  is? 

In  practice,  you  will  not  be  borrowing  from  BASIC  for 
everything  you  try  to  do.  One  reason  is  that  such  JSRing 
makes  your  program  far  less  portable,  less  easily  run  on  other 
computers  or  other  models  of  your  computer.  When  you  JSR 
to  an  address  within  your  ROM  set  to  save  yourself  the  trou- 
ble of  reinventing  the  wheel,  you  are,  unfortunately,  making 
your  program  applicable  only  to  machines  which  are  the  same 
model  as  yours. 

While  Commodore  has  been  better  than  many  computer 
companies  at  keeping  important  ROM  addresses  like  $FFD2  in 
the  same  place  in  new  models,  there  are  no  guarantees  that 
this  will  always  be  the  case. 

However,  if  you  want  your  program  to  work  on  many  dif- 
ferent computer  brands,  you'll  need  to  limit  the  degree  to 
which  you  make  it  ROM-specific.  Stick  to  the  few  essential 
ones  (see  the  equates  at  the  beginning  of  the  LADS  program 
for  the  few  ROM  routines  that  it  needed  to  use). 

If  you  try  to  get  too  tricky — using  your  BASIC'S  or  operat- 
ing system's  ROM  to  the  maximum — your  programs  will  be 
j""?  pretty  hard  to  translate  to  other  Commodore  computer  mod- 

els, not  to  mention  other  computer  brands.  For  example,  the 
subroutine  to  allocate  space  for  a  string  in  memory  is  found  at 
p"!  $D3D2  in  the  earliest  Commodore  PET  model.  A  later  version 

1  of  PET  BASIC  (Upgrade)  used  $D3CE,  and  the  current  models 

use  $C61D.  Although  Microsoft  BASIC  is  nearly  universally 
p*"j  used  in  personal  computers  (Atari  is  the  exception),  each 

—  computer's  version  differs  in  both  the  order  and  the  addresses 

of  key  subroutines. 
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FFCF 

4C 

15 

F2 

INPUT  one  byte 

FFD2 

4C 

66 

F2 

OUTPUT  one  byte 

FFD5 

4C 

01 

F4 

LOAD  something 

FFD8 

4C 

DD 

F6 

SAVE  something 

u 
u 


Jump  Tables  and  Other  Menus  j    j 

To  help  overcome  this  lack  of  portability,  some  computer 

manufacturers  set  aside  a  group  of  frequently  used  subroutines 

and  create  a  "jump  table,"  or,  as  Commodore  calls  it,  a  II 

Kernal,  for  them.  The  idea  is  that  future,  upgraded  BASIC  ver-  t~J 

sions  will  still  retain  this  table.  It  would  look  something  like 

this:  [J 


This  example  is  part  of  the  Commodore  Kernal  and  is  in- 
tended to  apply  to  all  future  versions  of  BASIC  on  Com- 
modore machines. 

One  interesting  thing  about  this  table  of  jumps  is  that 
there  is  a  trick  to  the  way  this  sort  of  table  works,  and  you 
might  want  to  use  it  yourself  sometime.  Notice  that  each 
member  of  the  table  begins  with  4C.  That's  the  JMP  instruc- 
tion and,  if  you  land  on  it,  the  computer  bounces  right  off  to 
the  address  which  follows. 

Now,  at  that  address  following  the  4C,  there  is  going  to 
be  a  subroutine  (so  it  will  end  in  RTS).  So,  when  we  JSR  to 
one  of  the  JMPs  inside  this  table,  to,  say,  FFD2,  we're  going  to 
land  on  a  JMP  and  rebound,  just  bounce  right  off  the  JMP  ta- 
ble to  the  correct  subroutine.  When  that  subroutine  finally  fin- 
ishes its  work  and  ends  in  RTS,  we  will  be  returned  to  our 
starting  place.  That's  how  a  JMP  table  works  and  it  can  be  a 
useful  technique. 

By  the  way,  the  PRINT  subroutine  is  a  fundamental  one 
in  any  computer  because  it  offers  you  so  much  value.  For  one 
thing,  it  keeps  track  of  the  cursor  position  which  is  in-  |    j 

cremented  each  time  you  access  PRINT.  It  works  semi- 
automatically,  and  you  don't  have  to  keep  track  of  where  you 

are  on  the  screen.  The  PRINT-the-character  routine  in  the  128  ) [ 

is  $FFD2  (65490  decimal).  This  is  a  very  important  address; 
you  should  memorize  it. 

For  convenience,  you  might  want  to  make  a  standard  j    1 

"header"  for  all  your  ML  source  programs  that  you  use  with  ' 

LADS.  It  would  consist  of  a  series  of  "equates"  which  define 
frequently  used  internal  subroutines  by  giving  them  labels:  *    ( 
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30  PRINT  =  $FFD2;  PRINTS  CHARACTER  IN 

ACCUMULATOR 
40  SCREEN  -  $0400;  LOCATION  OF  TEXT  SCREEN 

Then,  when  you're  writing  an  ML  source  program  using 
LADS  and  want  to  print  some  character,  you  just  JSR  PRINT. 
ML  can  thus  be  very  similar  to  BASIC  in  that  when  you  are 
going  to  use  a  known  subroutine,  a  subroutine  that  you've 
given  a  label  at  the  beginning  of  your  program  in  the  manner 
illustrated  above,  you  just  type  a  word  like  SCREEN  that 
means  something  to  your  program  and  also  means  something 
memorable  to  you.  You  might  want  to  use  the  routines  de- 
fined in  the  Defs  subprogram  of  LADS  as  a  useful  starter  set 
of  ROM  routines. 

The  same  PRINT  routine  will  work  for  a  printer  or  a  disk 
or  a  tape — anything  that  the  computer  sees  as  an  output  de- 
vice. However,  unless  you  open  a  file  to  one  of  the  other  de- 
vices, the  computer  defaults  to  (assumes)  the  screen  as  the 
output  device,  and  $FFD2  prints  there.  To  see  how  to  set  up 
different  output  targets,  see  the  Openl  source  code  of  LADS 
in  Appendix  D.  It  will  show  you  the  way  to  load  or  save  a 
program. 

So,  if  you  look  into  any  ML  program  and  discover  a  series 
of  JMPs  (4C  xx  xx  4C  xx  xx),  you've  found  a  jump  table.  Using 
a  jump  table  should  help  make  your  programs  compatible 
with  later  versions  of  BASIC  which  might  be  released. 

What's  Fastest? 

Since,  when  a  BASIC  program  runs,  it  is  JSRing  around  in- 
side itself,  how,  then,  is  a  JSR  into  BASIC  code  any  faster  than 
a  BASIC  program?  The  answer  is  that  a  program  written  en- 
tirely in  ML,  aside  from  the  fact  that  it  borrows  only  sparingly 
from  BASIC  prewritten  routines,  differs  from  BASIC  in  an  im- 
portant way. 

A  finished  ML  program  is  like  compiled  code;  that  is,  it  is 
ready  to  execute  without  any  overhead.  BASIC,  for  each  com- 
mand or  instruction,  must  be  interpreted  as  it  runs.  This  is 
why  BASIC  is  called  an  interpreter.  Each  instruction  must  be 
looked  up  in  a  table  to  find  its  address  in  ROM.  And  many 
other  aspects  of  a  BASIC  instruction  need  to  be  interpreted. 
All  this  takes  time.  Your  ML  code  will  contain  the  direct  ad- 
dresses for  its  JSRs.  When  that  ML  program  runs,  the  instruc- 
tions don't  need  elaborate  interpretation,  time-consuming 
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10  *=  $B00 

20  .s 

30  .o 

40  LOOP  JSR  $FFE4;  get  a  key  from  the  keyboard 

50  BEQ  LOOP;  if  no  key  pressed,  try  again 

60  BRK;  now  check  what's  in  the  accumulator 
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cross-checking,  table  lookups,  or  any  other  delay.  The  JSR  just 
leaps  into  the  right  area  of  BASIC  ROM  without  further  ado. 

There  are  special  programs  called  compilers  which  can 
take  a  BASIC  program  and  transform  (compile)  it  into  ML-like  .    i 

code  which  can  then  be  executed  like  ML,  without  having  to  I i 

interpret  each  command  during  the  program's  run.  The  JSRs 

are  within  the  compiled  program,  just  as  in  ML.  Compiled  ,    , 

programs  will  run  perhaps  20  to  40  times  faster  than  the  I 1 

BASIC  program  they  grew  out  of.  (Generally,  there  is  a  small 
price  to  pay  in  that  the  compiled  version  is  almost  always 
larger  than  its  BASIC  equivalent.) 

Compilers  are  interesting;  they  act  almost  like  automatic 
ML  writers.  You  write  it  in  BASIC,  and  they  translate  it  into 
an  ML-like  program.  Even  greater  improvements  in  speed  can 
be  achieved  if  a  program  uses  no  floating  point  (decimal 
points)  in  the  arithmetic.  Also,  there  are  "optimized"  com- 
pilers which  take  longer  during  the  translation  phase  to  com- 
pile the  finished  program,  but  which  try  to  create  the  fastest, 
most  efficient  compiled  program  design  possible.  No  compiler 
is  excessively  slow,  however.  A  good  optimizing  compiler  can 
translate  an  8K  BASIC  program  in  two  or  three  minutes.  Well, 
why  not  just  compile  BASIC  programs  and  forget  about  ML 
altogether?  The  main  reason  is  that  ML  is  always  far  faster 
than  even  optimized  compilations.  You  just  can't  beat  the  ef- 
ficiency of  hand-crafted  communications  which  speak  directly 
to  the  chip  in  its  own  language. 

GET  and  PRINT 

Two  of  the  most  common  activities  of  a  computer  program  are 
getting  characters  from  the  keyboard  and  printing  them  to  the 
screen.  To  illustrate  how  to  use  BASIC  from  within  an  ML  .     , 

program,  we'll  show  how  both  of  these  tasks  can  be  accom-  LJ 

plished  from  within  ML. 

Try  this  program  and  hit  a  key  on  the  keyboard.  Notice  , 

that  the  code  number  for  whatever  character  you  typed  on  the  } 1 

keyboard  appears  in  the  accumulator. 

The  128's  BASIC'S  GET: 
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This  routine  will  wait  until  the  user  types  in  a  character, 
but  will  not  show  a  cursor  on  the  screen.  Nor  will  it  print  an 
"echo,"  an  image  of  the  character  on  the  screen. 
!"-?  To  print  any  character  to  the  screen: 

2000    LDA  #$41      Put  the  character's  ASCII  value  into  the 

accumulator. 
2002    JSR   $FFD2  Print  it. 

If  you  combine  these  routines  into  a  "GET  and  PRINT," 
you  can  leave  out  the  LDA  #$41,  because  JSR  $FFE4  will  have 
left  the  value  of  whatever  key  you  typed  in  the  accumulator, 
and  JSR  $FFD2  will  print  whatever  is  in  the  accumulator  to 
the  next  available  location  onscreen.  Here's  the  completed 
GET  and  PRINT  routine: 

10  *=  $B00 

20  .S 

30  .O 

40  LOOP  JSR  $FFE4;  get  a  key  from  the  keyboard 

50  BEQ  LOOP;  if  no  key  pressed,  try  again 

60  JSR  $FFD2;  print  it 

However,  if  you  intend  to  use  or  analyze  what's  being 
typed  into  the  computer,  you  must  also  store  each  character 
somewhere  in  RAM: 

10  *=  $B00 

20  .S 

30  .O 

35  LDY  #0:STY  STOREY;  set  up  pointer  to  string  buffer 

40  LOOP  JSR  $FFE4;  get  a  key  from  the  keyboard 

50  BEQ  LOOP;  if  no  key  pressed,  try  again 

60  JSR  $FFD2;  print  it 

70  LDY  STOREY:STA  BUFFER,Y:INY:STY  STOREY;  save 
p™^  character  and  Y 

1  — '  80  JMP  LOOP;  get  another  character 

500  BUFFER  .BYTE  00000000000000000000000 
J"-;  510  STOREY  .BYTE  0;  safe  place  to  keep  the  value  of  Y 

$FFD2  doesn't  change  the  value  of  X  or  Y  when  we  JSR 
P_,  to  it.  When  it  RTSs  back  to  our  ML  program,  X  and  Y  are  the 

/_  1  same  as  when  we  JSRed  to  $FFD2.  Most  BASIC  ROM  routines, 

however,  aren't  that  considerate.  Usually,  they'll  use  X  and  Y 
rn  and  RTS  back  to  your  ML  with  those  registers  changed  un- 

I    \  predictably.  So,  it's  sometimes  necessary  to  preserve  the  val- 

ues in  X  or  Y,  prior  to  JSRing  into  ROM,  if  you're  using  X  or  Y 

r— ) 
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for  looping  or  other  purposes.  We've  done  that  in  the  example  i    ' 

above  by  setting  aside  a  byte  to  hold  Y  (line  510)  and  by  '— ' 

fetching,  updating,  and  saving  Y  when  necessary  (line  70). 

Notice  that  this  example  is  an  endless  loop:  It  has  no  way  i    i 

to  exit  its  loop.  You  would  need  to  add  a  CMP  #13  if  you  UJ 

wanted  to  exit  when  the  typist  hit  the  RETURN  key.  You 
would  CMP  #13:BEQ  END  to  branch  to  a  label  called  END  \    i 

which  you  put  somewhere  beyond  this  loop,  beyond  that  JMP  ' — ' 

LOOP  instruction  in  line  80.  You  could  insert  your  check  for 
carriage  return  at  line  55.  Or,  because  we've  set  aside  a  buffer 
with  only  23  bytes  to  hold  the  characters  (line  500),  you  might 
want  to  check  the  value  of  Y  and  CPY  #23:BEQ  END  to  pre- 
vent further  input  when  the  buffer  had  been  filled. 

In  any  event,  the  ML  routine  within  BASIC  ROM  which 
keeps  track  of  the  current  cursor  position  and  will  help  you 
print  things  to  the  screen  is  often  needed  in  ML  programming. 
$FFD2  will  handle  this  for  you. 

You  will  discover  that  there  are  many  freeze-dried  ML 
modules  sitting  in  BASIC.  These  routines  were  written  by  the 
professionals  who  built  BASIC  itself,  and  their  methods  can 
seem  intimidating  at  first.  However,  disassembling  some  of 
these  routines  and  picking  them  apart  is  a  good  way  to  dis- 
cover new  techniques,  new  efficiencies,  and  to  see  how  the 
best  ML  programs  are  constructed. 

Here's  another  example  to  look  at.  It  illustrates  how  to 
print  out  a  string,  the  length  of  which  is  known  in  advance. 
Although  this  is  less  common  than  the  zero-delimiter  method 
of  printing  strings  (BEQ  is  triggered  by  a  zero  at  the  end  of  the 
string),  you'll  still  see  this  printout  method  in  some  software: 

10  *=  $2000 

30  LENGTH  =  10  !  i 

40  PRINT  =  $FFD2  ^^ 

50  ; 

60  START  LDY  #0  i 

70  CLOSE  LDA  STRING, Y  LJ 

80  JSR  PRINT 

90  INY 

100  CPY  #LENGTH 

110  BNE  CLOSE 

120  RTS 

130  ; 

140  STRING  .BYTE  "SUPERDUPER 
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7"!  Studying  your  computer's  BASIC  is  worth  the  effort,  and 

1 —  it's  something  you  can  do  for  yourself.  You  won't  understand 

everything  (some  shortcuts  are  taken  which  are  obscure  in  the 
!""""]  extreme).  Nevertheless,  if  you've  got  some  time,  take  a  look  at 

a  particular  routine  and  see  if  you  can  see  the  logic  in  it,  its 
purpose  and  structure.  And,  as  you  can  see  by  the  example 
'~"j  above,  you  have  great  freedom  to  construct  the  customized 

---■  INPUT  routine  that  suits  your  ML  program  perfectly,  that  re- 

flects precisely  what  you  want  to  allow  or  disallow  the  user  to 
INPUT,  and  that  formats  to  the  screen  or  saves  in  a  buffer  in 
the  exact  way  that's  most  efficient  for  your  purposes. 


135 


I ) 

LJ 
U 
U 


u 
u 
u 

u 


■      Chapter  8 

•    Building  a  Program 


I ) 

LJ 
U 
U 


u 
u 
u 

u 


n 


i   [ 


Building  a  Program 


Using  what  we've  learned  so  far  and  adding  a  couple  of  new 
techniques,  let's  build  a  useful  program.  This  example  will  dem- 
P"")  onstrate  many  of  the  techniques  we've  discussed  and  will  also 

show  some  of  the  thought  processes  involved  in  writing  ML. 
Among  the  computer's  more  impressive  talents  is  search- 
ing. It  can  run  through  a  mass  of  information  and  find  some- 
thing very  quickly.  We  can  write  an  ML  routine  which  looks 
through  any  area  of  memory  to  find  matches  with  anything 
else.  Based  on  an  idea  by  Michael  Erperstorfer  published  in 
COMPUTE!  magazine,  this  ML  program  will  report  the  line 
number  of  all  the  matches  it  finds.  You'll  also  find  this  a  use- 
ful utility  to  keep  on  your  LADS  disk.  If  you  need  to  find  a 
particular  subroutine  in  a  long  source  code  file,  this 
"Searcher"  program  can  save  considerable  time  and  effort. 

Safe  Havens 

Before  we  go  through  some  typical  ML  program-building 
methods,  let's  review  the  "where  do  I  put  it?"  question.  ML 
can't  be  just  dropped  anywhere  in  RAM.  When  you  give  the 
starting  address  to  LADS  at  the  beginning  of  your  source  code 
with  the  *=  symbol,  you  can't  just  put  in  any  address  that 
pops  into  mind. 

There  are  other  things  going  on  in  the  computer  in  addi- 
tion to  your  hard-won  ML  program.  RAM  is  used  in  many 
ways.  There  is  always  the  possibility  that  you  want  to  have  a 
BASIC  program  coresident  with  your  ML  program.  If  so,  you'll 
J""}  need  to  figure  out  where  to  put  the  ML  so  that  it  won't  cover 

up,  or  be  covered  up  by,  the  BASIC.  Too,  BASIC  needs  to  use 
part  of  RAM  to  store  some  of  its  variables.  During  execution, 
these  variables  might  be  written  (POKEd)  into  your  vulnerable 
ML  if  you  located  it  in  a  vulnerable  zone.  That  would  fatally 
corrupt  your  ML. 

Also,  the  operating  system,  the  disk  operating  system, 
cassette  or  disk  loads,  printers — they  all  use  parts  of  RAM  for 
their  housekeeping  activities.  There  are  other  things  going  on 
besides  your  ML.  And  you  obviously  can't  put  your  ML  pro- 
gram into  ROM  addresses.  That's  impossible.  Nothing  can  be 
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POKEd  into  those  frozen  ROM  addresses;  they're  read  only  \  ''■> 

memory,  no  writing  allowed.  * — » 

This  is  one  good  use  for  a  map  of  the  128.  It  will  tell  you 
where  you  can  safely  store  your  programs  and  variables  with-  i    i 

out  interfering  with  space  used  by  the  computer  itself.  For  ex-  w 

ample,  assume  that  you're  writing  a  program  which  will  need 
to  access  the  disk  drive.  To  complicate  things,  you  want  to  use  i    i 

about  six  two-byte  spaces  in  zero  page  (the  lowest  256  bytes  u_j 

in  memory)  for  your  own  program.  ROM  routines  also  make 
heavy  use  of  zero  page,  but  you  can't  use  bytes  they'll  be 
using  since  the  ROM  routines  would  then  interfere  with  your 
data  and  mess  up  your  pointers.  The  solution  is  to  look  at  the 
map  (see  Appendix  C). 

To  solve  the  above  problem,  you'd  notice  that  addresses 
250-254  are  safe.  But  we  need  more  than  this.  Looking  at  the 
map  of  the  128,  you  can  see  that  addresses  99-111  are  used 
for  floating-point  operations  and  thus  can  be  expected  to  be 
safe,  too.  We'll  be  accessing  the  disk  drive  but  the  floating- 
point routines  won't  be  involved  in  this  program.  That  solves 
our  problem. 

On  the  128,  the  tape-drive  zero  page  usage  is  not  conve- 
niently contiguous,  but  you  can  still  find  two-byte  pairs  which 
are  safe.  Also,  if  you're  not  using  other  ROM  routines  in  your 
program,  look  for  their  zero  page  areas.  For  example,  the  floating- 
point accumulators  can  often  be  used  if  you're  not  accessing 
math  routines  in  ROM. 

You'll  also  be  able  to  stash  things  (though  not  for  zero 
page  access)  safely  in  various  other  places  in  RAM  where  your 
ML  program  won't  be  in  the  way.  If  you're  not  using  sprites, 
you  can  put  your  program  or  variables  between  addresses 
3584  and  4095.  Also  free  for  ML  use  is  the  foreign  language  H   , 

and  function  key  area  between  4864  and  7167  or  the  section  ~Cj> 

reserved  for  a  BASIC  program  even  when  bank  15  is  operative 
(7168-16384).  ,     j 

The  128  is  a  very  RAM-rich  machine,  though,  so  you'll  l^J 

also  be  able  to  use  most  of  banks  0  and  1  even  if  you  do  re- 
quire ROM  routines.  Just  switch  them  in  and  out  as  necessary,  .    j 
or  invoke  the  special  long-distance  LDA,  STA,  CMP,  JSR,  and              < — I 
JMP  Kernal  routines  available  in  the  128. 
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fn  Misleading  the  Computer 

If  the  ML  is  a  short  piece  of  program,  you  can  stash  it  into  the 
safe  $B00-$BFF  zone  mentioned  before,  the  cassette  drive 

P"!  buffer  area.  Because  this  safe  area  is  only  256  bytes  long,  and 

because  so  many  ML  routines  will  want  to  use  that  area,  it  can 
become  crowded.  Worse  yet,  it  isn't  100  percent  safe.  The  128 

f— }  uses  the  top  part  of  this  area  sometimes.  If  you  notice  odd 

things  happening,  memory  conflict  is  one  of  the  first  things  to 
suspect.  For  example,  you  might  be  able  to  run  an  ML  pro- 
gram at  $B00  the  first  time,  but  subsequent  SYSs  to  it  will 
crash.  If  you've  used  a  ROM  routine,  it  might  well  have  "bor- 
rowed" a  few  bytes  from  the  $B00  zone.  That  would  have  the 
effect  of  damaging  your  ML. 

An  alternative,  particularly  worthwhile  when  you're  using 
ML  as  an  extension  of  BASIC  and  they  are  supposed  to  work 
together,  is  to  deceive  the  computer  into  thinking  that  its  RAM 
is  smaller  than  it  really  is. 

Your  ML  will  be  truly  safe  if  your  computer  doesn't  even 
suspect  the  existence  of  some  set-aside  RAM.  It  will  leave  the 
now-safe  RAM  alone  because  you've  told  it  that  it  has  less 
RAM  than  it  really  does.  Nothing  can  overwrite  your  ML  pro- 
gram after  you've  misled  your  computer's  operating  system 
about  the  size  of  its  RAM  memory.  There  are  two  bytes  in 
zero  page  which  tell  the  computer  what  its  highest  RAM  ad- 
dress is  for  bank  1.  You  just  change  those  bytes  to  point  to  a 
lower  address.  You  can  have  your  ML  program  do  this  as  its 
first  job.  While  this  trick  is  effective  on  the  64,  the  128's  mem- 
ory management  system  makes  things  more  complicated. 
Nevertheless,  if  you  want  to  try,  these  crucial  top-of- 
memory  bytes  are  57,58  ($39,$3A  hex). 

p— i  To  repeat,  pointers  such  as  these  are  stored  in  LSB,MSB 

'    '  order.  That  is,  the  more  significant  byte  (the  one  that's  mul- 

tiplied by  256)  comes  second  (this  is  the  reverse  of  normality). 

]— -t  For  example,  $8000,  divided  between  two  bytes  in  this  top-of- 

'  RAM  pointer,  would  look  like  this: 

0039    00 
PI  003A   80 

As  we  mentioned  earlier,  this  odd  inversion  of  normal  nu- 
meric representation  is  a  peculiarity  of  the  8502  that  you  just 
have  to  get  used  to.  You  can  take  comfort  in  the  fact  that  the 
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8502  and  its  family  of  chips  have  far  fewer  peculiarities  and  il- 
logical rules  than  their  main  rivals,  the  Z80  family.  You  can  be 
driven  to  distraction  with  chips  where  the  language  is  frequently 
at  odds  with  the  way  humans  think.  Destinations  precede 
sources,  and  so  on.  It's  maddening.  Fortunately,  the  68000  O 

chip,  the  chip  in  the  Amiga,  is  a  sensible,  programmer-friendly 
chip,  too.  If  you  go  on  to  learn  how  to  work  with  this  new  .    i 

generation  of  chips,  the  8502  family  will  seem  both  familiar  Lj 

and  reasonable.  But  do  beware  of  the  pointer  inversion:  The 
LSB  is  stored  in  the  lower  byte  in  memory.  It's  a  small  price  to 
pay  for  an  otherwise  well-designed  microprocessor. 

Anyway,  you  can  lower  the  computer's  opinion  of  the 
top-of-RAM-memory,  thereby  making  a  safe  place  for  your 
ML  in  64  mode,  by  changing  only  the  MSB.  If  you  need  one 
page  (256  bytes),  POKE  58,  PEEK  (58)- 1.  For  four  pages,  POKE 
58,  PEEK  (58)— 4,  and  so  on.  You  don't  need  to  fiddle  around 
with  the  LSB  of  the  pointer.  Give  yourself  plenty  of  room. 
Note  that  for  the  POKEs  to  be  effective,  they  must  be  followed 
by  a  BASIC  CLR  (CLeaR  variables)  command.  The  full  state- 
ment would  be  something  like  POKE  58,  PEEK(58)-4:CLR. 
Since  the  CLR  erases  all  variable  values,  this  should  generally 
be  the  first  statement  in  any  program  in  which  this  technique 
is  used. 

This  chapter  also  introduces  an  important  consideration 
when  assembling  source  code  that's  larger  than  IK  (1024 
bytes).  When  your  work  begins  to  exceed  this  size,  you  should 
switch  to  disk-based  assembly  (see  Appendix  B  for  complete 
instructions).  The  reason  is  that  LADS  reserves  all  of  bank  1 
for  object  code  and  all  of  bank  0  for  source  code.  LADS  itself 
is  in  bank  15  (which  uses  the  same  RAM  as  bank  0)  and, 
when  you  are  assembling  with  RAMLADS — as  we  have  for  all  , 

the  examples  in  the  book  thus  far — small  source  code  will  ere-  LJ 

ate  no  memory  conflicts. 

However,  source  code  for  RAMLADS  resides  at  7168  and,  . 

as  you  type  in  more  source  code,  it  builds  up  from  there.  L^J 

RAMLADS  itself  resides  at  10000.  This  leaves  2832  bytes  free. 
During  assembly,  LADS  builds  its  label  array  down  from  .    , 

10000  and  so,  when  your  source  code  reaches  a  size  some-  1 I 

what  larger  than  IK,  the  labels  and  source  will  meet  and 

you'll  start  getting  error  messages  about  undefined  labels  that  , 

you  know  you've  defined,  and  so  forth.  |^J 

RAMLADS  is  best  for  trying  out  short,  under  IK,  source 
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<*~i  code.  When  your  program  grows  beyond  this  size,  you  need 

i-J  to  switch  to  DISKLADS.  With  DISKLADS,  source  code  or  ob- 

ject code  can  be  much  larger  since  each  source  file  is  loaded 
from  disk  into  bank  0  RAM  above  LADS,  assembly  takes  place 
on  the  source  code  in  memory,  and  the  resulting  object  code  is 
stored  in  bank  1  where  it  will  be  entirely  safe.  When  all  source 
files  have  been  assembled,  the  object  code  will  be  saved  to  disk. 
Because  of  all  the  comments,  the  source  code  of  Searcher, 
the  example  program  in  this  chapter,  is  4K  large.  You  can  type 
it  all  in  without  worry,  but  you  should  make  a  habit  of  first 
DSAVEing  source  code  prior  to  assembling  in  case  you  run 
into  memory  conflict  or  other  problems  during  the  assembly. 
It  is  necessary  to  invoke  DISKLADS  with  Searcher.  If  you  at- 
tempt to  assemble  it  via  RAMLADS,  LIST  will  reveal  that  part 
of  the  source  code  has  been  overwritten  by  the  label  array. 

Building  the  Code 

Now  we  return  to  the  subject  at  hand — building  an  ML  pro- 
gram. Most  people  find  it  easiest  to  mentally  divide  a  task  into 
several  tasks,  solve  the  individual  small  tasks,  and  then  weave 
them  all  together  into  a  complete  program.  That's  how  we'll 
attack  the  job  of  building  a  search  program. 

We  will  build  our  ML  program  in  pieces  and  then  tie 
them  all  together  at  the  end.  The  first  phase,  as  always,  is  the 
initialization.  We  set  up  the  variables  and  fill  in  the  pointers. 
Lines  90  and  100  define  two,  two-byte  zero  page  pointers.  L1L 
is  going  to  point  at  the  address  of  the  BASIC  line  we  are  cur- 
rently searching  through;  L2L  points  to  the  starting  address  of 
the  line  following  it. 

BASIC  stores  four  important  bytes  just  prior  to  the  start  of 
the  code  in  each  BASIC  line.  Take  a  look  at  Figure  8-1.  The 
first  two  bytes  contain  the  address  of  the  next  line  in  the 
BASIC  program.  Thus,  when  BASIC  has  finished  evaluating 
and  acting  upon  the  current  line,  it  will  already  know  where 
to  go  to  find  the  next  line.  This  is  called  linking. 

The  second  two  bytes  hold  the  line  number.  The  end  of  a 
BASIC  line  is  signaled  by  a  zero.  Zero  does  not  stand  for  any- 
thing in  the  ASCII  code  or  for  any  BASIC  command.  This  is 
quite  similar  to  the  way  we  signal  in  ML  programs  that  a  text 
message  is  finished — by  storing  a  zero  at  the  end  of  the  text. 
We  discussed  this  earlier  when  we  talked  of  delimiting  an 
ASCII  message. 
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If  there  are  three  zeros  in  a  row,  it  tells  BASIC  that  it  has 
reached  the  end  of  the  program  in  memory.  Three  zeros  is  a 
super  delimiter. 

But  back  to  our  examination  of  the  ML  program.  In  line 
110  is  a  definition  of  the  zero  page  location  which  holds  a 
two-byte  number  that  BASIC  looks  at  when  it  is  going  to  print 
a  line  number  on  the  screen.  We'll  want  to  store  line  numbers  ,, 

in  this  location  as  we  come  upon  them  during  the  execution  of  Lj 

our  ML  search.  Each  line  number  will  temporarily  sit  waiting 
in  case  a  match  is  found.  If  a  match  is  found,  the  program  will 
JSR  to  the  BASIC  ROM  routine  we're  calling  PLINE,  as  de- 
fined in  line  140.  This  routine  prints  a  line  number  on  the 
screen,  and  it  will  need  to  have  the  "current  line  number" 
where  it  expects  to  find  it. 

Line  120  establishes  that  BASIC  RAM  starts  at  $1C00, 
and  line  130  gives  the  address  of  the  "print  the  character  in 
the  accumulator"  ROM  routine.  Use  *=  $B00  to  put  the  object 
code  into  the  traditional  "safe"  RAM  area  to  store  short  ML 
programs. 

Refer  to  Program  8-1  to  follow  the  logic  of  the  construc- 
tion of  our  search  program.  The  search  is  initiated  by  typing  in 
line  0,  followed  by  the  item  we  want  to  locate.  It  might  be 
that  we  are  interested  in  removing  all  REM  statements  from  a 
program  to  shorten  it.  We  would  type  0REM  and  hit  RETURN 
to  enter  this  line  into  the  BASIC  program.  Then  we  would 
start  the  search  by  a  SYS  to  the  starting  address  of  the  ML 
program:  SYS  2816. 

By  entering  the  "sample"  string  or  command  into  the 
BASIC  program,  we  simplify  our  task  in  two  ways.  First,  if  the 
thing  we're  searching  for  is  a  string,  it  will  be  automatically 
stored  as  the  ASCII  code  for  that  string,  just  as  BASIC  stores  s    j 

strings.  O 

If  it  is  a  keyword  like  REM,  it  will  be  translated  into  the 
"tokenized,"  one-byte  representation  of  the  keyword,  just  as  .     . 

BASIC  stores  keywords.  L^J 

The  second  problem  this  method  solves  is  that  our  sample 
is  located  in  a  known  area  of  RAM.  By  looking  at  Figure  8-1,  ,    , 

you  can  tell  that  the  sample's  starting  address  will  always  be  I I 

the  start  of  BASIC  plus  five.  In  Program  8-1  that  means  $1C05 

(see  line  1090).  ,    j 
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Set  Up  the  Pointers 

Our  first  job,  as  always  when  we're  going  to  be  using  ROM 
routines,  is  to  switch  in  bank  15.  We  do  this  in  lines  190-200. 

Then  we'll  need  to  get  the  address  of  the  next  line  in  the  ,   j 

BASIC  program  we  are  searching.  And  then  we  need  to  store  L-j 

it  while  we  look  through  the  current  line.  The  way  that  BASIC 
lines  are  arranged,  we  come  upon  the  link  to  the  next  line's  (    i 

address  and  the  line  number  before  we  see  any  BASIC  code  it-  1 — f 

self.  Therefore,  the  first  order  of  business  is  to  put  the  address 
of  the  next  line  into  our  L1L  location  for  safekeeping.  Lines 
240-270  take  the  link  found  in  start-of-BASIC  RAM  (plus  one) 
and  move  it  to  the  storage  pointer  L1L. 

Next,  lines  320-380  check  to  see  if  we  have  reached  the 
end  of  the  BASIC  program.  It  would  be  the  end  if  we  had 
found  two  zeros  in  a  row  as  the  pointer  to  the  next  line's  ad- 
dress. If  it  is  the  end,  the  RTS  sends  us  back  to  BASIC  mode. 

The  subroutine  in  lines  540-720  saves  the  pointer  to  the 
following  line's  address  and  also  the  current  line  number. 

Note  the  double-byte  addition  in  lines  670-720.  We  al- 
ways CLC  before  any  addition.  If  adding  four  to  the  LSB  (line 
680)  results  in  a  carry,  we  want  to  be  sure  that  the  MSB  goes 
up  by  one  during  the  ADd  with  Carry  in  line  710.  At  first 
glance,  it  seems  to  make  no  sense  to  add  a  zero  in  that  line. 
What's  the  point?  We're  doing  an  addition  with  carry;  in  other 
words,  if  the  carry  flag  has  been  set  up  by  the  addition  of  four 
to  the  LSB  in  line  680,  then  the  MSB  will  have  one  added  to 
it.  That's  the  carry.  The  carry  flag  makes  this  happen. 

First  Characters 

When  you're  searching  for  something,  say,  your  car  in  a  park- 
ing lot,  you  look  for  something  distinctive.  You  might  search  s    , 

for  the  color  blue,  or  perhaps  a  plastic  flower  that  you've  at-  I ' 

tached  to  the  antenna.  You  certainly  don't  look  at  each  entire 
car,  at  the  hood,  the  wheels,  the  windows,  the  size,  the  color,  ,    , 

etcetera,  etcetera.  You  look  for  a  single  attribute;  then,  if  the  O 

car  is  blue,  you  compare  other  attributes  to  see  if  it  is  indeed 
entirely  the  same  as  yours.  ,    , 

Likewise,  it's  better  just  to  compare  the  first  character  in  a  t__j 

word  against  each  byte  in  the  searched  memory  than  to  try  to 
compare  the  entire  sample  word.  If  you  are  looking  for  the  ,    , 

word  MEM,  you  don't  want  to  stop  at  each  byte  in  memory  L^j 

and  see  if  M-E-M  starts  there.  Just  look  for  M's.  When  you 
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come  upon  an  M,  then  go  through  the  full  string  comparison. 
If  line  920  finds  a  first-character  match,  it  transfers  the  pro- 
gram to  the  subroutine  labeled  SAME  (line  1060)  which  will 
j— I  perform  a  thorough  comparison. 

On  the  other  hand,  if  the  routine  starting  at  line  890 
comes  upon  a  zero  (line  900),  it  knows  that  the  BASIC  line 
has  ended  (all  BASIC  lines  end  with  zero,  and  zero  is  not  used 
in  any  other  way  within  a  BASIC  program).  Our  search  pro- 
gram then  goes  down  to  STOPLINE  (line  1240),  which  puts 
the  "next  line"  address  pointer  into  the  "current  line"  pointer, 
and  the  whole  process  of  reading  a  new  BASIC  line  begins 
anew. 

If,  however,  a  perfect  match  was  found  (line  1100  found  a 
zero  at  the  end  of  the  0:REM  line,  showing  that  we  had  come 
to  the  end  of  the  sample  string),  we  go  to  PERFECT  and  it 
makes  a  JSR  to  print  out  the  line  number  (line  1390).  The 
PERFECT  subroutine  bounces  back  (RTS)  to  STOPLINE, 
which  replaces  the  "current  line"  (L1L)  pointer  with  the  "next 
line"  pointer  (L2L). 

Then  we  JMP  back  to  READLINE,  which,  once  again, 
pays  very  close  attention  to  zeros  to  see  if  the  whole  BASIC 
program  has  ended  with  a  pair  of  zeros.  We  have  now  re- 
turned to  the  start  of  the  main  loop  of  this  ML  program. 

This  all  sounds  more  complicated  than  it  is.  If  you've  fol- 
lowed it  so  far,  you  can  see  that  there  is  enormous  flexibility 
in  constructing  ML  programs.  If  you  want  to  put  the  STOP- 
LINE  segment  before  the  SAME  subroutine — go  ahead.  Self- 
contained  subroutines  are  not  position-dependent. 

It  is  quite  common  to  see  a  structure  like  this: 

Definitions 
SCREEN  =  $0400 
Initialization 
LDA  #15 
STA  $83 
Main  Loop 


START   JSR1 

1— 1 

JSR  2 

J   1 

JSR  3 

BEQ  START  Until  some  index  runs  out 

RTS                  To  BASIC 
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Subroutines 

1 

2  Each  ends  with  RTS  back  to  the  Main  Loop 

3 

DATA 

Table  1 

Table  2 

Table  3 


U 

u 
u 
u 

Li 


These  are  the  main  subdivisions  of  machine  language  pro- 
grams. If  you  use  this  structure,  you  will  find  that  it  simplifies 
locating  the  different  parts  of  a  program,  and  it  also  prevents 
nonprogram  data  (such  as  tables,  messages,  definitions)  from 
getting  mixed  in  with  the  program  code  proper.  LADS  is  de- 
signed using  this  nearly  universal  format.  Since  all  but  the 
shortest  programs  will  have  defined  variables,  initialization,  a 
main  loop,  a  cluster  of  subroutines,  and,  finally,  a  collection  of 
data  tables,  why  not  organize  all  your  programs  in  this  simple, 
straightforward,  and  sensible  way? 

Try  typing  in  the  source  code  in  Program  8-1  and  assem- 
bling it  with  LADS.  (Refer  to  Appendix  B  for  instructions  on 
using  LADS.)  As  mentioned  earlier,  because  of  the  length  of 
the  source  code,  you'll  need  to  save  it  on  disk  and  use 
DISKLADS.  After  you've  assembled  the  source  code,  you'll 
need  to  BLOAD  the  object  file  created  during  the  assembly. 
Next,  load  the  BASIC  program  you  wish  to  search  and  add 
line  number  0  containing  the  word  or  words  you  want  to 
seach  for.  Then  use  SYS  2816  to  activate  the  program;  that's 
where  it  sits  in  RAM. 

As  your  skills  improve,  you  will  likely  begin  to  appreciate, 
and  finally  embrace,  the  extraordinary  freedom  that  ML  con- 
fers on  the  programmer. 

At  first,  learning  ML  can  seem  fraught  with  apparently  [    j 

endless  obscure  tricks  and  rules.  It  can  even  seem  menacing,  ~" 

beyond  your  understanding.  It's  this  way  with  every  new  lan- 
guage because  the  words  are  still  new,  still  odd.  if 

Everyone  passes  through  this  (surprisingly  brief)  sense  of 
dread.  Once  you  know  how  to  tell  your  computer,  directly  in 

its  language,  how  to  print  something  on  the  screen,  you  don't  j j 

need  to  relearn  this  trick.  Things  fall  into  place.  It  won't  take 
as  long  as  it  might  now  seem  for  you  to  begin  to  grasp  the  rel- 
atively few  novelties  of  machine  language  programming.  ML  j    j 
isn't  the  theory  of  relativity;  it's  no  more  difficult  than  BASIC. 
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r~[  It's  just  a  new  vocabulary  for  the  same  programming  tech- 

'    '  niques  you've  been  using  with  BASIC. 

And  this  brief  sensation,  this  brief  confusion,  is  a  very 

r— ]  small  price  to  pay  for  the  flights  you  will  soon  be  taking 

through  your  computer.  Work  at  it.  Try  things.  Learn  how  to 
find  your  errors.  It's  not  circular — there  will  be  steady  ad- 

r~)  vances  in  your  understanding.  One  day  soon,  you'll  be  able  to 

easily  turbocharge  your  BASIC  programs  with  ML,  to  write 
convenient,  custom  utilities  like  our  search  routine,  and  to  do 
pretty  much  anything  you  could  want  to  do  with  your 
machine. 
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n      ML  Equivalents  of  BASIC 
n      Commands 


What  follows  is  a  small  dictionary,  arranged  alphabetically,  of 
the  major  BASIC  commands.  If  you  need  to  accomplish  some- 
thing in  ML — TAB,  for  example — look  it  up  in  this  chapter  to 
see  one  way  of  doing  it  in  ML.  Often,  because  ML  is  so  much 
freer  than  BASIC,  there  will  be  several  ways  to  go  about  a 
given  task. 

Of  these  choices,  one  might  work  faster,  one  might  take 
up  less  memory,  and  one  might  be  easier  to  program  and 
understand.  For  this  chapter,  example  routines  were  selected 
to  favor  those  which  are  easier  to  program  and  understand. 

At  ML's  extraordinary  speeds,  and  with  the  large  amounts 
of  RAM  memory  available  to  today's  computerists,  it  will  be 
rare  that  you  will  need  to  opt  for  velocity  or  memory 
efficiency. 

CLR 

In  BASIC,  this  clears  all  variables.  Its  primary  effect  is  to  reset 
pointers.  It  is  a  somewhat  abbreviated  form  of  NEW  since  it 
does  not  "blank  out"  your  program  as  NEW  does. 

CLR,  in  fact,  is  rarely  used. 

We  might  think  of  CLR,  in  ML,  as  the  initialization  phase 
of  a  program  which  erases  (fills  with  zeros)  the  memory  loca- 
tions you've  set  aside  to  hold  your  ML  flags,  pointers, 
counters,  and  so  on.  You  can  see  an  example  of  this  in  the 
LADS  source  code  in  Eval  between  lines  30  and  70  (Appendix 
D). 

Before  an  ML  program  runs,  you  will  usually  want  to  be 
sure  that  some  of  its  variables  are  set  to  zero.  If  they  are  in 
different  places  in  memory,  you  will  need  to  zero  them 
individually: 

2000    LDA  #$0 

2002    STA  $1990     Put  zero  into  one  of  the  "variables." 
2005    STA  $1994    Continue  putting  zero  into  each  byte  which 
needs  to  be  initialized. 
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On  the  other  hand,  if  you've  put  all  your  variables  to-  j     i 

gether  at  the  end,  the  job  is  easy:  Just  loop  through  the  lis:,  ' — ' 
putting  zero  in  each  variable.  BASIC  sets  up  a  group  of  its 

variables  (pointers)  in  zero  page,  so  you  can  use  a  loop  to  zero  t    / 

them  out:  ' — > 

2000    LDA  #$0 

2002    LDY  #$0F     Y  will  be  the  counter.  There  are  15  bytes  to  zero  )     [ 

out  in  this  example.  ' — ' 

2004    STA  $199,Y  The  highest  of  the  15  bytes. 

2007  DEY 

2008  BNE  $2004     Let  Y  count  down  to  zero,  BNEing  until  Y  is 

zero,  then  the  Branch  if  Not  Equal  will  let  the 
program  fall  through  to  the  next  instruction  at 
$200A. 

CONT 

This  BASIC  command  allows  your  program  to  pick  up  where 
it  left  off  after  a  STOP  command.  You  might  want  to  look  at 
STOP,  below.  In  ML,  you  can't  usually  get  a  running  program 
to  stop  with  the  RUN/STOP  key.  If  you  like,  you  could  write 
a  subroutine  which  checks  to  see  if  a  particular  key  is  being 
held  down  on  the  keyboard  and,  if  it  is,  BRK: 

3000    JSR    $FFE4;  Routine  to  get  the  key  currently  pressed. 

3003    BEQ  3000;     If  nothing  is  currently  pressed,  keep  looking. 

3005    CMP  #13       This  is  the  RETURN  key  on  your  machine,  but 
you'll  want  CMP  here  to  the  value  that  appears 
in  the  "currently  pressed"  byte  for  the  key  you 
select  as  your  "stop"  key.  It  could  be  any  key.  If 
you  want  to  use  A  for  your  "stop"  key,  try 
CMP  #$41. 

3007    BNE  $300A   If  it's  not  your  target  key,  jump  to  RTS. 

3009    BRK  If  it  is  the  target,  BRK...  |_J 

300A  RTS  back  to  the  routine  which  called  this  subroutine. 

However,  the  above  routine  requires  that  some  key  be  .    , 

pressed.  It  will  keep  branching  back  to  3000  until  some  key  is  I I 

pressed.  This  is  the  kind  of  input  you  would  use  when  you 

printed  a  menu  and  wanted  the  program  to  pause  until  a  ,    , 

selection  was  made.  i i 

There  is,  however,  a  location  in  zero  page,  the  byte  at 

$D4,  which  detects  keypresses  on  the  fly.  You  could  LDA  , 

$D4:CMP  #10:BEQ  FOUNDA  (FOUNDA  is  your  routine  that  1_J 
does  something  whenever  the  user  presses  the  A).  Notice  that 


158 


U 


n 


H 
n 


i   i 


n 


DATA 


the  code  for  the  letter  A  has  a  value  of  ten  here.  Unlike  a  JSR 
$FFE4,  the  value  returned  from  location  $D4  is  not  regular 
ASCII.  It's  a  different  code,  the  "keyboard  matrix  code,"  and 
there's  no  use  learning  it  or  having  a  chart  of  it.  Carriage  re- 
turn is  1,  the  letter  A  is  10;  when  no  key  is  pressed,  $D4  con- 
tains an  88.  If  you  need  to  know  sometime  what  value  will  be 
in  $D4  for  a  particular  keypress,  just  look  at  $D4  via  BASIC 
with  this  simple  program: 

10  PRINT  PEEK(212);:GOTO  10 

and  then  press  the  key  you're  interested  in. 

Now  back  to  CONT,  the  matter  at  hand.  The  8502  places 
the  program  counter  (plus  two)  on  the  stack  after  a  BRK.  A 
close  analogy  to  BASIC  is  the  placement  of  BRK  within  ML 
code  to  cause  a  halt  to  program  execution.  Then,  after  examin- 
ing registers  or  variables  or  buffers  (places  that  hold  input  or 
output  before  it's  received  or  sent),  you  can  restart  your  pro- 
gram by  using  the  monitor  G  (go)  command.  G  is  the  equiva- 
lent of  CONT. 

DATA 

In  BASIC,  DATA  announces  that  the  items  following  the  word 
DATA  are  to  be  considered  pieces  of  information  (as  opposed 
to  being  thought  of  as  parts  of  the  program).  That  is,  the  pro- 
gram will  probably  use  this  data,  but  the  data  elements  are  not 
BASIC  commands. 

In  ML,  such  a  zone  of  "nonprogram"  is  called  a  table.  It  is 
unique  only  in  that  the  program  counter  never  starts  trying  to 
run  through  a  table  to  carry  out  instructions.  This  never  hap- 
pens because  you  never  transfer  program  control,  using  JMP, 
JSR,  or  a  branching  instruction,  to  anything  within  a  table. 
(This  is  similar  to  the  way  that  BASIC  slides  right  over  DATA 
lines.)  There  are  no  meaningful  instructions  inside  a  table.  To 
see  what  a  table  looks  like  and  what  it  does,  see  the  Tables 
subprogram  in  the  LADS  source  code  in  Appendix  D. 

To  keep  things  simple,  tables  of  data  are  usually  stored 
together  either  above  or  below  the  program.  Usually,  tables 
are  stored  above,  at  the  very  end  of  the  ML  program  (see  Fig- 
ure 9-1). 

Tables  can  hold  messages  that  are  to  be  printed  to  the 
screen,  hold  variables,  hold  flags  (temporary  indicators),  and 
so  on.  If  you  disassemble  your  BASIC  in  ROM,  you'll  find  the 
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words  STOP,  RUN,  LIST,  and  so  forth,  gathered  together  in  a 
table.  You  can  suspect  a  data  table  when  your  disassembler 
starts  giving  lots  of  ???  error  messages.  It  cannot  find  groups  of 
meaningful  opcodes  within  tables. 

Figure  9-1.  Typical  ML  Program  Organization 


DATA 

INITIALIZATION 

MAIN 
LOOP 

SUBROUTINES 

DATA 

Bottom  of  Memory 
Start  of  ML  Program 


U 
U 

u 
u 
u 


DIM 

With  its  automatic  string  handling,  array  management,  and  er- 
ror messages,  BASIC  makes  life  easy  for  the  programmer. 

The  price  you  pay  for  this  hand  holding  is  that  it  slows 
down  the  program  when  it's  run.  In  ML,  the  DIMensioning  of 
space  in  memory  for  variables  is  not  explicitly  handled  by  the 
computer.  You  must  make  a  note  that  you  are  setting  aside 
memory  from  $6000  to  $6500,  or  whatever,  to  hold  variables. 
It  helps  to  make  a  simple  map  of  this  "dimensioned"  memory 
so  that  you  know  where  permanent  strings,  constants,  variable 
strings,  and  variables,  flags,  and  so  on,  are  within  the  dimen- 
sioned zone.  Because  this  set-aside  memory  will  not  contain 
meaningful  ML  instructions,  it  is  generally  placed  at  the  end  of 
the  actual  ML  program.  With  LADS,  you  can  make  Tables  the 
final  file  in  your  chain  of  files.  That  will  automatically  put  the 
tables  at  the  end  of  your  program  proper.  To  define  data 
(string  or  numeric),  you  use  the  .BYTE  instruction;  .BYTE  auto- 
matically makes  space,  like  DIM. 
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END 


A  particular  chunk  of  memory  (where,  and  how  much,  is 
up  to  you)  is  reserved;  that's  all.  You  don't  write  any  instruc- 
tions in  8502  ML  to  set  aside  the  memory;  you  just  start  using 
the  .BYTE  pseudo-op  and  it  fills  in  your  tables.  That's  why  it's 
best  to  place  tables  at  the  end  of  your  program.  This  way, 
they  can  be  enlarged  conveniently  without  affecting  any  other 
part  of  the  program. 


END 

There  are  several  ways  to  make  a  graceful  exit  from  ML  pro- 
grams. You  can  JMP  to  the  "warm  start"  address  ($4003).  Or 
you  can  go  to  the  "cold  start"  address  ($4000). 

If  you  went  into  the  ML  from  BASIC  with  a  SYS,  you  can 
return  to  BASIC  with  an  RTS.  Recall  that  every  JSR  matches 
up  with  its  own  RTS.  Every  time  you  use  a  JSR,  it  shoves  its 
"return  here"  address  onto  the  top  of  the  stack.  If  the  com- 
puter finds  another  JSR  (before  any  RTS),  it  will  shove  another 
return  address  on  top  of  the  first  one.  So,  after  two  JSRs,  the 
stack  contains  two  return  addresses.  When  the  first  RTS  is  en- 
countered, the  top  return  address  is  lifted  from  the  stack  and 
put  into  the  program  counter  so  that  the  program  returns  con- 
trol to  the  current  instruction  following  the  most  recent  JSR. 

When  the  next  RTS  is  encountered,  it  pulls  its  appropriate 
return  (waiting  for  it  on  the  stack),  and  so  on.  The  effect  of  a 
SYS  from  BASIC  is  like  a  JSR  from  within  ML.  The  return  ad- 
dress to  the  correct  spot  within  BASIC  is  put  on  the  stack.  In 
this  way,  if  you  are  within  ML  and  there  is  an  RTS  (without 
any  preceding  JSR),  what's  on  the  stack  will  be  a  return-to- 
BASIC  address  left  there  by  SYS  when  you  first  went  into  ML. 

Another  way  to  END  is  to  put  a  BRK  in  your  ML  code. 
j—"j  This  drops  you  into  the  machine's  monitor.  Normally,  you  use 

BRKs  during  program  debugging.  When  the  program  is  finished, 
though,  you  would  not  want  this  ungraceful  exit  any  more 
J™"]  than  you  would  want  to  end  a  BASIC  program  with  STOP. 

In  fact,  many  ML  programs,  if  they  stand  alone  and  are 
not  part  of  a  larger  BASIC  program,  never  end  at  all.  They  are 
Pi  an  endless  loop.  The  main  loop  just  keeps  cycling  over  and 

over.  A  game  will  not  end  until  you  turn  off  the  power.  After 
each  game,  you  see  the  score  and  are  asked  to  press  a  key 
when  you  are  ready  for  the  next  game.  Arcade  games  which 
cost  a  quarter  will  ask  for  another  quarter,  but  they  don't  end. 

161 


FOR-NEXT 


u 

u 

They  go  into  "attract  mode."  The  game  graphics  are  left  run-  .     > 

ning  onscreen  to  interest  new  customers.  LJ 

An  ML  word  processor  will  cycle  through  its  main  loop, 
waiting  for  keys  to  be  pressed,  words  to  be  written,  format  or  i    , 

disk  instructions  to  be  given.  Here,  too,  it  is  common  to  find  ' 1 

that  the  word  processor  takes  over  the  machine,  and  you  can- 
not stop  it  without  turning  the  computer  off.  Among  other  ,     , 
things,  such  an  endless  loop  protects  software  from  being  pi-  LJ 
rated.  Since  it  takes  control  of  the  machine,  this  makes  it 
harder  for  someone  to  save  it  or  examine  it  once  it's  in  RAM? 
Some  such  programs  are  "autobooting"  in  that  they  start 
themselves  running  as  soon  as  they  are  loaded  into  the 
computer. 

BASIC,  itself  an  ML  program,  also  loops  endlessly  until 
you  power  down.  When  a  program  is  running,  all  sorts  of 
things  are  happening.  BASIC  is  an  interpreter,  which  means 
that  it  must  look  up  each  word  (like  INT)  it  comes  across  dur- 
ing a  RUN  (interpreting,  or  translating,  its  meaning  into  ma- 
chine-understandable JSRs).  Then,  BASIC  executes  the  correct 
sequence  of  ML  actions  from  its  collection  of  routines. 

In  contrast  to  BASIC  RUNs,  BASIC  spends  99  percent  of 
its  time  waiting  for  you  to  program  with  it.  This  waiting  for 
you  to  press  keys  is  its  endless  loop,  a  tight,  small  loop 
indeed. 

It  would  look  like  our  "which  key  is  pressed?"  routine: 

2000  LOOP  LDA  $D4;  THE  "WHICH  KEY  IS  BEING 

PRESSED"  LOCATION 
2002  CMP  #88;  IF  88,  KEEP  LOOPING 
2004  BEQ  LOOP 

If  there  is  an  88  in  $D4,  this  means  that  no  key  has  been 
pressed.  So,  we  keep  looping  until  the  value  in  address  $D4  is  i    | 

something  other  than  88.  This  setup  is  similar  to  INPUT  in  * — ' 

BASIC  because  not  only  does  it  wait  until  a  key  is  pressed,  but 
it  also  leaves  a  unique  value  of  the  key  in  the  accumulator 
when  it's  finished. 

FOR-NEXT 

Everyone  has  had  to  use  delay  loops  in  BASIC  (FOR  T  =„  1 
TO  1000:  NEXT  T)  which  are  also  tight  loops,  sometimes 
called  do-nothing  loops  because  nothing  happens  between  the 
FOR  and  the  NEXT  except  the  passage  of  time.  For  example, 
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when  you  need  to  let  the  user  read  something  on  the  screen, 
it's  sometimes  easier  just  to  use  a  delay  loop  than  to  say, 
"When  finished  reading,  press  any  key." 
r— |  In  any  case,  you'll  need  to  use  delay  loops  in  ML  just  to 

-  -- >  slow  ML  itself  down.  In  a  game,  the  ball  can  fly  across  the 

screen.  It  can  get  so  fast,  in  fact,  that  you  can't  see  it.  It  just 
f>  "appears"  when  it  bounces  off  a  wall.  And,  of  course,  you'll 

1    '  need  to  use  loops  in  many  other  situations.  Loops  of  all  kinds 

are  fundamental  programming  techniques. 

In  ML,  you  don't  have  that  convenient  little  counter  (T  in 
the  BASIC  FOR-NEXT  example  above)  which  decides  when  to 
stop  the  loop.  When  T  becomes  1000,  go  to  the  instructions 
beyond  the  word  NEXT.  Again,  you  must  set  up  and  check 
your  counter  variable  by  yourself. 

If  the  loop  is  going  to  be  smaller  than  255  cycles,  you  can 
use  the  X  register  as  the  counter — Y  is  saved  for  the  very  use- 
ful indirect  indexed  addressing  discussed  in  Chapter  4:  LDA 
(96), Y.  Anyway,  by  using  X,  you  can  count  to  200  by: 

2000    LDX  #200      (or  $C8  hex) 

2002  DEX 

2003  BNE  $2002 

For  loops  involving  counters  larger  than  255,  you'll  need 
to  use  two  bytes  to  count  down,  one  going  from  255  to  0  and 
then  clicking  (like  a  gear)  the  other  (more  significant)  byte. 

To  count  to  512: 

2000    LDA  #$2 

2002    STA  $6000    Put  the  2  into  address  6000,  our  MSB,  most 
significant  byte,  counter. 

2004  LDX  #$0       Set  X  to  0  so  that  its  first  DEX  will  make  it  255. 

Further  DEXs  will  count  down  again  to  0,  when 
""*"1  it  will  click  the  MSB  down  from  2  to  1  and  then 

-  l  finally  to  0. 

2006  DEX 

2007  BNE  $2006 

2009  DEC  $6000    Click  the  number  in  address  6000  down  1. 

200B  BNE  $2006 

Here  we  used  the  X  register  as  the  LSB  (least  significant 
byte)  and  address  6000  as  the  MSB.  Why  use  address  6000? 
Why  not?  Use  any  RAM  byte  you  want  that  won't  interfere 
with  other  things  going  on  in  the  computer.  In  practice,  you'll 
want  to  set  aside  a  byte  in  your  Tables  at  the  end  of  your  ML 
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program  to  be  sure  that  it's  not  going  to  interfere  with  some-  .     ■ 

thing.  See  DATA  above  for  a  discussion  of  Tables.  1 I 

We  could  use  addresses  $FA  and  $FB  to  hold  the  MSB/LSB 

if  we  wanted.  This  is  commonly  useful  because  then  address  ,    , 

$FA  (or  some  available,  two-byte  space  in  zero  page)  can  be  l_J 
used  for  LDA  ($FA),Y.  You  would  print  a  message  to  the 

screen  using  the  combination  of  a  zero  page  counter  and  LDA  .    , 

(zero  page  address), Y.  LJ 

FOR-NEXT-STEP 

Here  you  would  just  increase  your  counter  (usually  X  or  Y) 
more  than  once.  To  create  FOR  I  =  100  TO  1  STEP  -2  you 
could  use: 

2000  LDX  #100 

2002  DEX 

2003  DEX 

2004  BNE  $2002 

For  larger  numbers  you  create  a  counter  which  uses  two 
bytes,  working  together,  to  keep  count  of  the  events.  Follow- 
ing our  example  above  for  FOR-NEXT,  we  could  translate  FOR 
I  =  512  TO  0  STEP  -2: 

LDA  #$2 

STA  COUNTER  This  is  going  to  hold  our  MSB. 

LDX  #$0  X  is  holding  our  LSB. 

DEX 

DEX  Here  we  click  X  down  a  second  time, 

for  -2. 
BNE  $2006 
DEC  COUNTER 
BNE  $2006 

400    COUNTER  .BYTE  0;  A  single  byte  set  aside  in  our  Tables  | J 

(In  this  example,  we've  shown  how  you  would  create 
LADS  source  code  to  set  aside  a  COUNTER  byte  above  the  |    , 

main  code.  However,  the  addresses  of  this  code,  2000-200C,  w_j 

are  not  known  when  you  write  source  code.  They  are  created 
after  you  activate  LADS.  They're  here  just  for  illustrative  pur-  j    | 

poses.  You  don't  type  in  addresses  when  writing  source  code  for  u^ 

LADS.) 

To  count  up,  use  the  CoMPare  instruction.  FOR  I  =  1  TO 

50  STEP  3: 
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200 

2000 

210 

2002 

220 

2004 

230 

2006 

240 

2007 

250 

2008 

260 

200A 

270 

200c 

n 


GOSUB 


n 

n 

n 


2000  LDX  #$0 

2002  INX 

2003  INX 

2004  INX 

2005  CPX   #$50 
2007  BNE  $2002 

For  larger  STEP  sizes,  you  can  use  a  nested  loop  within 
the  larger  one.  This  would  avoid  a  whole  slew  of  INXs.  To 
write  the  ML  equivalent  of  FOR  I  =  1  TO  50  STEP  10: 

2000  LDX  #$0 

2002  LDY  #$0 

2004  INY 

2005  CPY  #$0A 
2007  BNE  $2004 
2009  CPX   #$32 
200B  BNE  $2002 

GET 

Every  computer  must  have  that  important  "which  key  is  being 
pressed?"  address,  where  it  holds  the  value  of  a  character 
typed  in  from  the  keyboard.  To  GET,  you  create  a  very  small 
loop  which  tests  this  address.  See  a  complete  description  of 
this  technique  under  CONT  above. 

GOSUB 

This  is  nearly  identical  to  BASIC.  Use  JSR  $NNNN  and  you 
will  go  to  a  subroutine  at  address  NNNN  instead  of  a  line 
number  as  in  BASIC.  (NNNN  just  means  that  you  can  sub- 
stitute any  hex  number  for  the  NNNN  that  you  want  to.  This 
is  a  form  of  math  shorthand.)  LADS  allows  you  to  give  labels, 

Jl  names  to  JSR  to,  instead  of  addresses.  A  simple  assembler  like 

the  one  in  the  monitor  does  not  allow  labels.  You  are  respon- 
sible  (as  with  DATA  tables,  variables,  and  so  on)  for  keeping  a 

;    \  list  of  your  subroutine  addresses  and  the  parameters  involved  if 

you're  not  using  LADS. 

Parameters  are  the  number  or  numbers  handed  to  a  sub- 
routine to  give  it  information  it  needs.  Quite  often,  BASIC 
subroutines  work  with  the  variables  already  established  within 
the  BASIC  program.  In  ML,  though,  managing  variables  is  up 
to  you.  Subroutines  are  useful  because  they  can  perform  tasks 
repeatedly  without  needing  to  be  written  into  the  body  of  the 
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program  each  time  the  task  is  to  be  carried  out.  Beyond  this, 
they  can  be  generalized  so  that  a  single  subroutine  can  act  in  a 
variety  of  ways,  depending  upon  the  variable  (the  parameter) 
which  is  passed  to  it. 

A  delay  loop  to  slow  up  a  program  could  be  general  in 
the  sense  that  the  amount  of  delay  is  handed  to  the  subroutine 
each  time.  The  delay  can,  in  this  way,  be  of  differing  dura- 
tions, depending  on  what  it  gets  as  a  parameter  from  the  main 
routine. 

Let's  say  that  we've  decided  to  use  address  $40  to  pass 
parameters  to  subroutines.  We  could  pass  a  delay  of  five  cy- 
cles of  the  loop  by: 

2000    LDA  #$5 
The  Main  Program    2002    STA  $40 
2004    JSR    $5000 


U 

u 
u 
u 
u 


5000 
5002 


The  Subroutine 


DEC 
BEQ 


5004  LDY 

5006  DEY 

5007  BNE 
5009  JMP 
500C  RTS 


$40 
$500C 


#$0 

$5006 
$5000 


If  address  $40  has  counted 
all  the  way  down  from  5 
to  0,  RTS  back  to  the  main 
program. 


A  delay  which  lasted  twice  as  long  as  the  above  would 
merely  require  a  single  change  to  the  calling  routine:  2000 
LDA  #$0A. 

GOTO 

In  ML,  it's  JMP.  JMP  is  like  JSR,  except  the  address  you  leap 
away  from  is  not  saved  anywhere.  You  jump,  but  cannot  use 
an  RTS  to  find  your  way  back. 

There  are  two  basic  kinds  of  branching  in  computing.  A 
conditional  branch  would  be  CMP  #0:BEQ  5000.  The  condition 
of  equality  is  tested  by  BEQ,  Branch  if  EQual.  BNE  tests  a  con- 
dition of  inequality,  Branch  if  Not  Equal.  Likewise,  BCC 
(Branch  if  Carry  is  Clear)  and  the  rest  of  these  branches  are 
testing  conditions  within  the  program. 
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GOTO 


i    i 


[-"]  GOTO  and  JMP  do  not  depend  on  any  conditions  within 

the  program,  so  they  are  unconditional  branches.  The  question 
arises  when  you  use  a  GOTO:  Why  did  you  write  a  part  of 
!— j  your  program  that  you  must  always  (unconditionally)  jump 

'  over?  GOTO  and  JMP  are  sometimes  used  to  patch  up  a  pro- 

gram, but  used  without  restraint,  they  can  make  your  program 
hard  to  understand  later.  On  the  other  hand,  JMP  can  many 
times  be  the  best  solution  to  a  programming  problem.  In  fact, 
it  is  hard  to  imagine  ML  programming  without  it. 

One  additional  note  about  JMP:  It  makes  a  program 
nonrelocatable.  If  you  later  need  to  move  your  whole  ML  pro- 
gram to  a  different  part  of  memory,  all  the  JMPs  (and  JSRs) 
need  to  be  checked  to  see  if  they  are  pointing  to  addresses 
which  are  no  longer  correct.  (JMP  or  JSR  into  your  BASIC 
ROMs  will  still  be  the  same,  but  not  those  which  are  targeted 
to  addresses  within  the  ML  program.) 

2000    JMP  $2005 

2003  LDY  #$3 
2005    LDA  #$5 

If  you  moved  this  little  program  up  to  $5000,  everything 
would  survive  intact  and  work  correctly  except  the  JMP  $2005. 
It  would  still  say  to  jump  to  $2005,  but  it  should  say  to  jump 
to  $5005,  after  the  move.  You  have  to  go  through  with  a  dis- 
assembly and  check  for  all  these  incorrect  JMPs.  To  make  your 
programs  more  "relocatable,"  you  can  use  a  special  trick  with 
unconditional  branching  which  will  move  without  needing  to 
be  fixed: 

2000    LDY  #$0 

2002    BEQ  $2005     Since  we  just  loaded  Y  with  a  zero,  this  Branch 
if  EQual  to  zero  instruction  will  always  be  true 
|     i  and  cause  a  pseudo-JMP. 

2004  NOP 

2005  LDA 

Your  monitor  includes  a  "moveit"  routine,  invoked  with  T 
(Transfer),  which  will  take  an  ML  program  and  relocate  it 

f"|  somewhere  else  in  memory  for  you.  You  can  go  into  the  mon- 

itor and  type  T  2000  2006  5000  (you  give  the  monitor  these 
numbers  in  hex).  The  third  number  is  the  target  address.  The 

f"~j  first  and  second  are  the  start  and  end  of  the  program  you 

want  to  move. 


n 
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IF-THEN 


2004 

BEQ  $200D 

2006 

LDA  #$0A 

2008 

STA  $57 

200A 

JMP   $2011 

200D 

LDA  #$14 

200F 

STA  $57 

2011 

u 

u 


The  best  solution  to  relocatability,  however,  is  LADS.  ]    j 

With  it,  you  never  JMP  to  actual  addresses;  rather,  you  JMP  or  ' — ' 
JSR  or  branch  to  labels.  This  way,  relocating  your  program 

couldn't  be  simpler.  You  just  change  the  start  address  with  *=  j    j 

and  reassemble.  Everything  is  taken  care  of  and  the  program  ' — ' 
reassembles  to  the  new  location  flawlessly.  With  LADS,  the 

example  above  is  written  like  this:  i    i 

100  JMP  NEXTROUTINE 

110  LDY  #3 

120  NEXTROUTINE  LDA  #5 

(The  numbers  at  the  left  are  not  addresses;  they  are  line 
numbers  for  your  convenience  when  writing  the  program,  and 
they  have  no  effect  on  the  resulting  ML  code  after  assembly.) 

IF-THEN 

This  familiar  and  fundamental  computing  structure  is  accom- 
plished in  ML  with  the  combination  CMP-BNE  or  any  other 
conditional  branch:  BEQ,  BCC,  and  so  forth.  Sometimes,  the  IF 
half  isn't  even  necessary.  Here's  how  it  would  look: 

2000    LDA  $57        What's  in  address  $57? 
2002    CMP  #$0F     Is  it  $0F,  15  decimal? 

IF  it  is,  branch  up  to  $200D. 

Or  ELSE,  put  a  $0A,  10  decimal,  into  address 

$57. 

And  jump  over  the  THEN  part. 

THEN,  put  a  $14,  20  decimal,  into  address  $57. 

Continue  with  the  program.... 

Often,  though,  your  flags  are  already  set  by  an  action,  ,    , 

making  the  CMP  unnecessary.  For  example,  if  you  want  to  1 I 

branch  to  $200D  if  the  number  in  address  $57  is  zero,  just 

LDA  $57:BEQ  $200D.  This  works  because  the  act  of  loading 

the  accumulator  will  affect  the  status  register  flags.  You  don't 

need  to  CMP  #0  because  the  zero  flag  will  be  set  if  a  zero  was 

just  loaded  into  the  accumulator.  It  won't  hurt  anything  to  use  ,    , 

a  CMP,  but  you'll  find  many  cases  in  ML  programming  where  l^j 

you  can  shorten  and  simplify  your  coding  if  you  wish  to.  As 

you  gain  experience,  you  will  see  these  patterns  and  learn  .    . 

what  affects  the  status  register  flags.  L_] 
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PI  INPUT 

This  is  a  series  of  GETs,  echoed  to  the  screen  as  they  are 
typed  in,  which  end  when  the  typist  hits  the  RETURN  key. 
jj  The  reason  for  the  echo  (the  symbol  for  each  key  typed  is  re- 

produced on  the  screen)  is  that  few  people  enjoy  typing  with- 
out seeing  what  they've  typed.  This  also  allows  for  error  cor- 
rection using  cursor  control  keys  or  DELETE  and  INSERT  keys. 
To  handle  all  of  these  actions,  an  INPUT  routine  must  be 
fairly  complicated.  We  don't  want,  for  example,  the  DELETE 
to  become  a  character  within  the  string.  We  want  it  to  act  im- 
mediately on  the  string  being  entered  during  the  INPUT,  to 
erase  a  mistake. 

Our  INPUT  routine  must  also  be  smart  enough  to  know 
what  to  add  to  the  string  and  what  keys  are  intended  only  to 
modify  it.  Here  is  the  basis  for  constructing  your  own  ML  IN- 
PUT. It  simply  receives  a  character  from  the  keyboard,  prints 
it  to  the  screen,  and  ends  when  the  RETURN  key  is  pressed. 
We'll  write  this  INPUT  as  a  subroutine.  That  simply  means 
that  when  the  13  (ASCII  for  carriage  return)  is  encountered, 
we'll  perform  an  RTS  back  to  a  point  just  following  the  main 
program  address  which  JSRed  to  our  INPUT  routine.  Let's  do 
it  in  the  LADS  source  code  format,  with  line  numbers  instead 
of  addresses: 

10  *=  $B00 

20  .S 

30  .O 

40  LOOP  JSR  $FFE4:BEQ 

LOOP;  If  we  got  a  zero,  no  key  had  been 

pressed 

50  JSR  $FFD2;  Print  the  character  to  the  screen 

|— [  60  CMP  #13;  Is  it  a  carriage  return 

'-    '  70  BNE  LOOP;  If  not,  return  for  more  keypresses 

80  RTS;  Otherwise  return  to  the  calling 

I — |  routine 

If  you  try  this  out,  you'll  notice  that  even  the  cursor  keys 
and  delete,  screen  clear,  and  so  forth,  work  correctly.  This  is 
i— I  because  when  you  JSR  $FFD2  (PRINT),  it  is  just  as  if  you 

printed  any  character  from  BASIC  (with  cursor  control  codes 
embedded  in  a  string).  This  INPUT  could  be,  however,  much 
P—j  more  complex.  As  it  stands,  it  will  hold  the  string  on  the 

'  screen  only.  To  save  the  string,  you  would  need  to  store  it  in 

some  buffer  of  yours  in  addition  to  its  appearance  on  the 
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screen.  However,  if  you're  going  to  store  the  string  into  some  i     j 

safe  location  where  you  are  keeping  string  variables,  you'll  ! — ' 


U 
U 


need  to  refuse  storage  to  such  things  as  the  delete  character  or 
your  stored  string  will  be  corrupted  (will  include  delete)  if  the 
user  needs  to  correct  a  misspelling.  Or  you  might  want  to  pre- 
vent the  user  from  hitting  a  key  like  carriage  return.  In  that 
case,  just  CMP  #13:BEQ  LOOP  so  that  nothing  is  echoed  to 
the  screen  or  stored  in  your  string  when  the  user  trys  to  enter 
that  particular  key. 

The  great  freedom  you  have  with  ML  is  that  you  can  re- 
define anything  you  want.  You  can  softkey:  define  a  key's 
meaning  via  software;  have  any  key  perform  any  task  you 
want.  You  might  even  decide  to  use  the  $  key  to  DELETE. 

Along  with  this  freedom  goes  the  responsibility  for 
organizing,  writing,  and  debugging  these  routines. 

LET 

Although  this  word  is  still  available  on  most  BASICs,  it  is  a 
holdover  from  the  early  days  of  computing.  It  is  supposed  to 
remind  you  that  statements  like  LET  NAME  =  NAME  +  4  is 
an  assignment  of  a  value  to  a  variable,  not  an  algebraic  equa- 
tion. The  two  numbers  on  either  side  of  the  equal  sign,  in 
BASIC,  are  not  intended  to  be  equal  in  the  algebraic  sense. 
Most  people  write  NAME  =  NAME  +  4  without  using  LET. 
The  function  of  LET  applies,  though,  to  ML  as  well  as  to 
BASIC:  We  must  assign  values  to  variables. 

In  the  128,  for  example,  where  the  RAM  bank  can  change 
depending  on  how  you  configure  the  computer,  there  has  to 
be  a  place  where  we  can  find  out  which  bank  is  the  current 
bank  (it's  address  $FF00).  Likewise,  a  program  will  sometimes 
require  that  you  assign  meanings  to  string  variables,  counters, 
and  the  like.  This  can  be  part  of  the  initialization  process,  the 
tasks  performed  before  the  real  program,  your  main  routine, 
gets  started.  Or  it  can  happen  during  the  execution  of  the 
main  loop.  In  either  case,  there  has  to  be  an  ML  way  to  estab- 
lish, to  assign,  variables.  This  also  means  that  you  must  have 

zones  of  memory  set  aside  to  hold  these  variables  unless,  like  j \ 

the  bank-switching  location,  the  computer  has  already  defined 

a  variable.  Normally,  you  will  store  your  variables  as  a  group 

at  the  end  of  an  ML  program.  j j 

For  strings,  you  can  think  of  LET  as  the  establishment  of 
a  location  in  memory.  In  our  INPUT  example  above,  we  might 
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[— j  have  included  an  instruction  which  would  have  sent  the 

characters  from  the  keyboard  to  a  table  of  strings  as  well  as 
echoing  them  to  the  screen.  If  so,  there  would  have  to  be  a 

["""I  way  of  managing  these  strings.  For  a  discussion  on  the  two 

most  common  ways  of  dealing  with  strings  in  ML,  see  Chapter 
6  under  the  subhead  "Dealing  with  Strings." 

|—" j  In  general,  you  will  probably  find  that  you  program  in 

ML  using  somewhat  fewer  variables  than  in  BASIC.  There  are 
three  reasons  for  this: 

1.  You  will  probably  not  write  many  programs  in  ML  like 
databases  where  you  manipulate  hundreds  of  names,  ad- 
dresses, and  so  forth.  It  might  be  somewhat  inefficient  to 
create  an  entire  database  management  program,  an  in- 
ventory program  for  example,  in  ML.  Keeping  track  of  the 
variables  would  require  careful  programming.  (For  an  ex- 
ample database  manager,  see  LADS's  Equate  and  Array 
subprograms,  Appendix  D.) 

The  value  of  ML  is  its  speed  of  execution,  but  its 
drawback  is  that  it  requires  more  precise  programming  and, 
at  least  for  beginners,  can  take  more  time  to  write.  So,  for 
an  inventory  program,  you  could  write  the  bulk  of  the  pro- 
gram in  BASIC  and  simply  attach  ML  routines  for  sorting 
and  searching  tasks  within  the  program. 

2.  The  variables  in  ML  are  often  handled  within  a  series  of 
instructions  (not  held  elsewhere  as  BASIC  variables  are). 
FOR  I  =  1  TO  10  :  NEXT  I  becomes  LDY  #1:INY:CPY 
#10:BNE. 

Here,  the  BASIC  variable  is  counted  for  you  and 
stored  outside  the  body  of  the  program.  The  ML  "variable," 
though,  is  counted  by  the  program  itself.  ML  has  no  inter- 
[""!  preter  which  handles  such  things.  If  you  want  a  loop,  you 

must  construct  all  of  its  components  yourself. 

3.  In  BASIC,  it  is  tempting  to  assign  values  to  variables  at  the 
|~~j  start  of  the  program  and  then  to  refer  to  them  later  by  their 

1  variable  names,  as  in  10  BALL  =  79.  Then,  anytime  you 

want  to  PRINT  the  BALL  to  the  screen,  you  could  say, 

j~"1  PRINT  CHR$(BALL).  Alternatively,  you  might  define  it  this 

way  in  BASIC:  10  BALL$  =  "O".  In  either  case,  your  pro- 
gram will  later  refer  to  the  word  BALL.  In  this  example  we 

P~l  are  assuming  that  the  number  207  will  place  a  ball  charac- 

ter on  your  screen  (the  letter  O). 
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In  ML  we  can  use  variable  names  precisely  the  same  way  t    j 

if  we  are  programming  with  an  advanced  assembler  like  ' — ' 

LADS.  However,  with  an  elementary  assembler  like  the  one  in 
the  monitor,  you  will  just  LDA  #207,  STA  (screen  position)  i    i 

each  time.  Some  people  like  to  put  the  207  into  their  zone  of  <— ' 

variables  (that  arbitrary  area  of  memory  set  up  at  the  end  of  a 
program  to  hold  tables,  counters,  and  important  addresses). 
They  can  pull  it  out  of  that  zone  whenever  it's  needed.  That  is 
somewhat  cumbersome,  though,  and  slower.  You  would  LDA 
1015,  STA  (screen  position),  assuming  you  had  put  a  207  into 
this  "ball"  address,  1015,  earlier. 

Obviously,  a  value  like  BALL  will  always  remain  the  same 
throughout  a  program.  The  ball  will  look  like  a  ball  in  your 
game,  whatever  else  happens.  So,  it's  not  a  true  variable;  it 
does  not  vary.  It  is  constant.  A  true  variable  must  be  located  in 
your  "zone  of  variables,"  your  variable  table. 

It  cannot  be  part  of  the  body  of  your  program  itself  (as  in 
LDA  #207)  because  it  will  change.  You  don't  know  when  writ- 
ing your  program  what  the  variable  will  be.  So  you  can't  use 
immediate  mode  addressing  because  it  might  not  be  a  #207. 
You  have  to  LDA  1015  from  within  your  table  of  variables. 

Elsewhere  in  the  program  you  have  one  or  more  STA 
1015  or  INC  1015  or  some  other  manipulation  of  this  address 
which  keeps  updating  this  variable.  In  effect,  ML  makes  you 
responsible  for  setting  aside  areas  which  are  safe  to  hold  vari- 
ables if  you  are  using  the  monitor  assembler.  What's  more, 
you  have  to  remember  the  addresses  and  update  the  variables 
in  those  addresses  whenever  necessary.  This  is  why  it  is  so 
useful  to  keep  a  piece  of  paper  next  to  you  when  you  are  writ- 
ing ML  using  the  monitor.  The  paper  lists  the  start  and  end 
addresses  of  the  zone  of  variables,  the  table.  You  write  down 
the  specific  address  of  each  variable  as  you  write  your  pro- 
gram. LADS,  of  course,  makes  variable  zones  and  names  auto- 
matic with  the  .BYTE  pseudo-op.  See  LADS's  Tables  sub-  i    i 
program  (Appendix  D)  to  see  how  variables  (and  constants)  l^J 
can  be  handled  efficiently. 

I     I 

LIST  UJ 

This  is  done  via  a  disassembler.  It  will  not  have  line  numbers 

(though,  again,  advanced  assembler  packages  like  LADS  do  j | 

have  line  numbers).  You  will  see  the  address  of  each  instruc- 
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P~|  tion  in  memory.  You  can  look  over  your  work  and  plan  debug- 

1  ging  strategies,  where  to  set  BRKs  into  problem  areas,  and  so  on. 

The  most  common  way  to  list  and  check  your  work,  how- 
|~~]  ever,  is  to  read  over  the  source  code.  This  does  not  require  a 

disassembler.  You  write  LADS  source  code  as  if  it  were  a 
BASIC  program  and,  thus,  can  LIST  it  and  modify  it  as  if  it 
r~l  were  a  BASIC  program.  There  is  a  subtle  difference  between 

'  studying  source  code  and  studying  object  code  (via  dis- 

assembly). The  former  is  most  useful  for  making  modifications 
and  for  locating  the  more  obvious  bugs.  The  latter  is  for  pa- 
tiently tracking  down  those  last  few  stubborn  bugs  that  no 
amount  of  reading  over  the  source  code  will  reveal. 

LOAD 

The  method  of  saving  and  loading  an  ML  program  varies  from 
computer  to  computer.  You  have  two  options:  loading  from 
within  the  monitor  or  from  BASIC.  When  you  finish  working 
on  a  program,  or  a  piece  of  a  program,  on  the  mini-assembler, 
you  will  know  the  starting  and  ending  addresses  of  your 
work.  Using  these,  you  can  save  to  disk  or  tape  using  the  S 
monitor  command  (described  in  Chapter  3).  To  load,  the  sim- 
plest way  is  just  to  L  "FILENAME",  1  (for  tape)  or  ,8  (for  disk). 
You  can  also  load  ML  when  you're  in  BASIC  mode  by 
BLOAD.  With  both  the  monitor's  L  and  BASIC'S  BLOAD  com- 
mands, you  can  reassign  your  ML  routine  to  a  different  target 
address  (see  your  manual).  However,  this  will  not  adjust  the 
JSRs,  and  so  on,  so  you  haven't  really  relocated  the  program, 
and  it  probably  would  not  run  at  the  new  location.  To  truly 
relocate  it,  you  need  to  change  the  start  address  *=  and  re- 
assemble  it  with  LADS.  However,  loading  in  a  version  of  your 

I    j  ML  program  to  a  different  location  with  the  L  command  and 

then  loading  in  another  version  in  its  normal  location  does 
allow  you  to  compare  them  with  the  monitor's  C  command. 

I    i  To  see  how  to  save  and  load  from  within  your  ML  pro- 

grams, to  write  ML  which  itself  saves  and  loads  files,  please 
refer  to  the  Openl  subprogram  of  LADS  in  Appendix  D. 
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NEW 

In  Microsoft  BASIC,  this  has  the  effect  of  resetting  some  point- 
ers which  make  the  machine  think  that  you  are  going  to  start 
over  again.  The  next  program  line  you  type  in  will  be  put  at 
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the  "start-of-a-BASIC-program"  area  of  memory.  Some 
computers,  the  Atari  for  example,  even  wash  memory  by  fill- 
ing it  with  zeros.  There  is  no  special  command  in  ML  for 
NEWing  an  area  of  memory,  though  the  monitor  has  a  "fill  i    i 

memory"  option  which  will  fill  an  area  of  memory  as  large  as  ' — ' 


U 


you  want  with  whatever  value  you  choose. 

The  reason  that  NEW  is  not  found  in  ML  is  that  you  do 
not  always  write  your  programs  in  the  same  area  of  memory 
as  you  do  in  BASIC,  building  up  from  some  predictable  ad- 
dress. You  might  have  a  subroutine  floating  up  in  high  mem- 
ory, another  way  down  low,  your  table  of  variables  at  the  end, 
and  your  main  program  in  the  middle.  Or  you  might  not. 
We've  been  using  $2000  as  our  starting  address  for  many  of 
the  examples  in  this  book  and  $5000  for  subroutines,  but  this 
is  entirely  arbitrary. 

To  "NEW"  in  ML,  just  start  assembling  over  the  old 
program. 

Alternatively,  you  could  just  turn  the  power  off  and  then 
back, on  again.  This  would,  however,  have  the  disadvantage  of 
wiping  out  LADS  along  with  your  program. 

ON-GOSUB 

In  BASIC,  you  are  expecting  to  test  values  from  among  a 
group  of  numbers:  1,  2,  3,  4,  5,  ....  The  value  of  X  must  fall 
within  this  narrow  range:  ON  X  GOSUB  100,  200,  300,  ...  (X 
must  be  1  or  2  or  3  here).  In  other  words,  you  could  not 
conveniently  test  for  widely  separated  values  of  X  (18,  55, 
220).  There  is  also  an  improved  form  of  ON-GOSUB  where 
you  can  test  for  any  values.  If  your  computer  were  testing  the 
temperature  of  your  bath  water: 

CASE  [_] 

80  OF  GOSUB  HOT  ENDOF 

100  OF  GOSUB  VERYHOT  ENDOF 

120  OF  GOSUB  INTOLERABLE  ENDOF  I     I 

ENDCASE  L-J 

ML  permits  you  the  greater  freedom  of  the  CASE  struc- 
ture. Using  CMP,  you  can  perform  a  multiple  branch  test:  | j 

2000    LDA  $96        Get  a  value,  perhaps  input  from  the  keyboard. 
2002    CMP  #$50     Decimal  80  ,     ■ 

2004    BNE  $2009  |_J 

2006    JSR    $5000     Where  you  would  print  "hot,"  following  our  ex- 
ample of  CASE 
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ON-GOTO 


2009  CMP  #$64  Decimal  100 
200B    BNE  $2011 
200D  JSR    $5020  Print  "very  hot" 

2010  CMP  #$78  Decimal  120 
2012    BNE  $2017 

2014    JSR    $5030  Print  "intolerable" 

pH  This  illustrates  one  way  that  bugs  get  into  ML — by  not 

cleanly  entering  and  leaving  subroutines.  The  potential  prob- 
lem here  is  triggering  the  CMPs  more  than  once.  Since  you  are 
JSRing  and  then  will  be  RTSing  back  to  within  the  multiple 
branch  test  above,  you  will  have  to  be  sure  that  the  subroutines 
up  at  $5000  do  not  change  the  value  of  the  accumulator.  If  the 
accumulator  started  out  with  a  value  of  $50  and,  somehow, 
the  subroutine  at  $5000  left  a  $64  in  the  accumulator,  you 
would  print  "hot"  and  then  also  print  "very  hot."  One  way 
around  this  would  be  to  put  a  zero  into  the  accumulator 
before  returning  from  each  of  the  subroutines  (LDA  #$0).  This 
assumes  that  none  of  your  tests,  none  of  your  cases,  responds 
to  a  zero.  « 

ON-GOTO 

This  is  more  common  in  ML  than  the  ON-GOSUB  structure 
above.  It  eliminates  the  need  to  worry  about  what  is  in  the 
accumulator  when  you  return  from  the  subroutines.  Instead  of 
RTSing  back,  you  jump  back,  following  all  the  branch  tests. 

2000    LDA  $96 


2002     CMP  #$50 

2004    BNE  $2009 

2006    JMP   $5000 

Print  "hot" 

2009    CMP  #$64 

200B    BNE  $2010 

200D  JMP   $5020 

Print  "very  hot" 

2010    CMP  #$78 

2012    BNE  $2017 

2014    JMP   $5030 

Print  "intolerable" 

2017 

All  the  subroutines  JMP  $2017  when  they 

finish. 

Instead  of  RTS,  each  of  the  subroutines  will  JMP  back  to 
$2017,  which  lets  the  program  continue  without  accidentally 
"triggering"  one  of  the  other  tests  with  something  left  in  the 
accumulator  during  the  execution  of  one  of  the  subroutines. 
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PRINT 

u 

PRINT 

!   I 

You  could  print  out 

a  message  in  the  following  way: 

i f 

2000    LDY  #$0 

2002    LDA  #72 

The  letter  H 

u 

2004    STA  $0400,Y 

An  address  on  the  screen 

2007    INY 

2008    LDA  #69 

The  letter  E 

u 

200A   STA  $0400,Y 

200D   INY 

200E    LDA  #76 

The  letter  L 

2010    STA  $0400,Y 

2013    INY 

2014    LDA  #76 

The  letter  L 

2016    STA  $0400,Y 

2019    INY 

201A  LDA  #79 

The  letter  O 

201C    STA  $0400,Y 

But  this  is  clearly  a  clumsy,  memory-hungry  way  to  go 
about  it.  In  fact,  it  would  be  absurd  to  print  out  a  long  mes- 
sage this  way.  The  most  common  ML  method  involves  putting 
message  strings  into  a  data  table  and  ending  each  message 
with  a  zero.  Zero  is  never  a  printing  character  in  computers;  to 
print  the  number  zero,  you  use  176:  LDA  #$30,  STA  $0400. 
So,  true  zero  (not  the  code  for  the  character  0)  can  be  used  as 
a  delimiter  to  let  the  printing  routine  know  that  you've  fin- 
ished the  message.  In  a  data  table,  we  first  put  in  the  message 
"hello": 


1000 

$48    H 

1001 

$45    E 

1002 

$4C  L 

1003 

$4C  L 

1004 

$4F    O 

1005 

$00 

The  delimiter 

1006 

$48    H 

1007 

$49    I 

Another  message 

1008 

$0 

Another  delimiter 

LI 


u 

Such  a  message  table  can  be  as  long  as  you  need;  it  holds 
all  your  messages  and  they  can  be  used  again  and  again:  }    j 

2000    LDY  #$0 

2002    LDA  $1000,Y 

2005    BEQ  $200F      If  the  zero  flag  is  set,  it  must  mean  that  we've  [] 

reached  the  delimiter,  so  we  branch  out  of  this  "~~ 

printing  routine. 
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2007    STA  $0400,Y   Put  it  on  the  screen. 
200A   INY 


200B    JMP  $2002       Go  back  and  get  the  next  letter  in  the  message. 
200F  Continue  with  the  program. 

Had  we  wanted  to  print  HI,  the  only  change  necessary 
would  have  been  to  put  $1006  into  the  LDA  at  address  $2003. 
To  change  the  location  on  the  screen  that  the  message  starts 
printing,  we  could  just  put  some  other  address  into  $2008. 
The  message  table,  then,  is  just  a  mass  of  words,  separated  by 
zeros,  in  RAM  memory. 

The  process  of  printing  messages  is  even  simpler  using 
the  LADS  label-based  assembler  and  its  .BYTE  trick  for  storing 
numbers  or  words: 

10  SCREEN  =  $0400 
100  LDY  #0:MORE  LDA  MESSAGE, Y:BEQ  FINISH 
110  STA  SCREEN,Y:INY:JMP  MORE 

with,  at  the  end  of  your  source  code,  the  following  line  in- 
cluded somewhere  in  your  table  of  variables,  your  data: 

400  MESSAGE  .BYTE  "HELLO":.BYTE  0 
410  MESSAGE1  .BYTE  "HI":.BYTE  0 

See  the  Tables  section  of  LADS  (Appendix  D)  for  more 
examples  of  message  storage. 

The  fastest  way  to  print  to  the  screen,  especially  if  your 
program  will  be  doing  a  lot  of  printing,  is  to  create  a  sub- 
routine which  will  print  any  of  your  messages.  It  can  use  some 
bytes  in  zero  page  (addresses  0-255)  to  hold  the  location  of 
the  message  within  your  table  of  data. 

To  put  an  address  into  zero  page,  you  will  need  to  put  it 
into  two  bytes.  Addresses  are  too  big  to  fit  into  one  byte.  With 
r"i  LADS,  you  can  use  the  #<  and  #>  pseudo-ops  to  extract  the 

'    >  LSB  and  MSB  of  a  label  and  thus  store  the  address  of  your 

message  into  a  zero  page  pointer: 

10  MSGADDRESS  =  56 

20  SCREEN  =  $0400 

100  LDA  #<MESSAGE:STA  MSGADDRESS;  set  up  pointer 
110  LDA  #>MESSAGE:STA  MSGADDRESS +1 
120  JSR  PRINTMSG;  go  to  universal  print  subroutine 
500  PRINTMSG  LDY  #0:LOOP  LDA  (MSGADDRESS), Y:BEQ 

END:STA  SCREEN,Y 
510  STA  SCREEN, Y:INY:JMP  LOOP 
520  END  RTS 


n 
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This  same  trick  can  be  done  with  the  simple  assembler  in  the 
monitor,  but  it  is  more  cumbersome. 

First,  you  split  the  hex  number  in  two.  The  left  two  digits, 
$10,  are  the  MSB  (most  significant  byte)  and  the  right  digits, 
$00,  make  up  the  LSB  (least  significant  byte).  If  you  are  going 
to  put  this  target  address  into  zero  page  at  56  (decimal): 

2000    LDA  #$00        LSB 


2002    STA  $56 

2004    LDA  #$10 

MSB 

2006    STA  $57 

2008    JSR    $5000 

Printout  subroutine 

5000    LDY  #$0 

5002    LDA  ($56)Y 

5004    BEQ  $5013 

If  zero,  return  from  subroutine 

5006    STA  $0400, Y 

to  screen. 

5009    INY 

500A  JMP   $5002 

500D  RTS 

One  drawback  to  this  PRINT  subroutine  we've  con- 
structed is  that  it  will  always  print  any  messages  to  the  same 
place  on  the  screen.  That  $0400  is  frozen  into  your  subroutine. 
Solution?  Use  another  zero  page  pair  of  bytes  to  hold  the 
screen  address.  Then,  your  calling  routine  sets  up  the  message 
address  as  above,  but  also  goes  on  to  specify  a  screen  address 
as  well. 

The  128's  screen  starts  at  $0400  (1024  decimal),  so  you 
will  want  to  put  0  and  4  into  the  LSB  and  MSB  respectively 
for  your  screen  pointer. 

2000    LDA  #$00      LSB 


U 

u 

u 
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LI 


2002 

STA  $56 

Set  up  message  address 

2004 

LDA  #$10 

MSB 

1     j 

2006 

STA  $57 

LJ 

2008 

LDA  #$0 

LSB 

200A 

STA  $58 

We'll  just  use  the  next  two  bytes  in  zero  page 
above  our  message  address  for  the  screen 
address. 

u 

200C 

LDA  #$4 

MSB 

u 

200E 

STA  $59 

2010 

JSR    $5000 

5000 

LDY  #$0 

L 

5002 

LDA  ($56)Y 

5004 

BEQ  $500D 

If  zero,  return  from  subroutine... 
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5006    STA  ($58),Y  to  screen. 

5009    INY 

500A  JMP   $5002 

500D  RTS 

The  easiest  way  to  print  messages  to  particular  places  on 
the  screen,  however,  is  to  use  the  128's  built-in  BASIC  PRINT 
routine  to  send  the  characters,  one  by  one,  each  to  the  next 
cursor  position  onscreen.  The  built-in  routine  updates  and 
keeps  track  of  the  current  cursor  position  for  you.  So,  you  can 
get  around  having  to  keep  a  screen  pointer  in  zero  page  this 
way.  In  the  example  immediately  above,  just  replace  line  5006 
with  JSR  $FFD2  (the  128's  PRINT  routine)  and  remove  lines 
2008-200E. 

READ 

There  is  no  reason  for  a  reading  of  data  in  ML.  Variables  are 
not  placed  into  "DATA  statements."  They  are  entered  into  a 
table  when  you  are  programming.  The  purpose  of  READ,  in 
BASIC,  is  to  assign  variable  names  to  raw  data,  or  to  take  a 
group  of  data  and  move  it  somewhere,  or  to  manipulate  it  into 
an  array  of  variables.  These  things  are  handled  by  you,  not  by 
the  computer,  in  ML  programming. 

If  you  need  to  access  a  piece  of  information,  you  set  up 
the  addresses  of  the  datum  and  the  target  address  to  which 
you  are  moving  it.  (See  the  PRINT  routines  above.)  As  always, 
in  ML  you  are  expected  to  keep  track  of  the  locations  of  your 
variables.  If  you  are  using  the  simple  assembler  in  the  mon- 
itor, you  must  keep  a  map  of  data  locations,  vectors,  tables, 
and  subroutine  locations.  This  pad  of  paper  is  always  next  to 
you  as  you  program  in  ML.  It  would  seem  that  you  would 

[""")  need  many  notes,  but  in  practice  an  average  program  of,  say, 

1000  bytes  could  be  mapped  out  and  commented  on,  using 
only  one  sheet. 

j"""j  Alternatively,  with  more  sophisticated  assemblers  like 

LADS,  the  labels  themselves  within  the  program  will  keep 
track  of  things  for  you,  and  embedded  comments  serve  to  re- 
mind you  of  the  use  and  function  of  all  data. 


I      ! 

H 
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REM 

You  do  this  on  a  pad  of  paper,  too,  when  working  with  a  sim- 
ple assembler.  If  you  want  to  comment  or  make  notes  about 
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your  program  (and  it  can  be  a  necessary,  valuable  explanation  ,     , 

of  what's  going  on),  you  can  disassemble  some  ML  code  like  a  I 1 

BASIC  listing.  If  you  have  a  printer,  you  can  make  notes  on 

the  printed  disassembly.  If  you  don't  use  a  printer,  make  notes  ,    , 

on  your  pad  to  explain  the  purpose  of  each  subroutine,  the  1 } 

parameters  it  expects  to  get,  and  the  results  or  changes  it 
effects. 

The  more  sophisticated  assemblers  like  LADS  will  permit  ' ! 

comments  within  the  source  code.  As  you  program,  you  can 
include  REMarks  by  typing  a  semicolon,  which  is  a  signal  to 
the  assembler  to  ignore  the  REMarks  when  it  is  assembling 
your  program.  In  these  assemblers,  you  are  working  much 
closer  to  the  way  you  work  in  BASIC.  Your  REMarks  remain 
part  of  the  source  program,  and  can  be  listed  out  and  studied. 

RETURN 

RTS  works  the  same  way  that  RETURN  does  in  BASIC:  It 
takes  you  back  to  just  after  the  JSR  (GOSUB)  that  sent  control 
of  the  program  away  from  the  main  program  and  into  a  sub- 
routine. JSR  pushes,  onto  the  stack,  the  address  which  im- 
mediately follows  the  JSR  itself.  That  address,  then,  sits  on  the 
stack,  waiting  until  the  next  RTS  is  encountered.  When  an 
RTS  occurs,  the  address  is  pulled  from  the  stack  and  placed 
into  the  program  counter.  This  has  the  effect  of  transferring 
program  control  back  to  the  instruction  just  after  the  JSR. 

RUN 

There  are  several  ways  to  start  an  ML  program.  If  you  are  tak- 
ing off  into  ML  from  BASIC,  you  just  SYS  to  it  by  giving  its 
address  (in  decimal)  as  the  argument  of  the  SYS.  This  acts  just 
like  JSR  and  will  return  control  to  BASIC,  just  as  RETURN 
would,  when  there  is  an  unmatched  RTS  in  the  ML  program. 

By  unmatched,  we  mean  the  first  RTS  which  is  not  part  of  a  (    i 

JSR/RTS  pair.  SYS  can  take  you  into  ML  either  in  immediate  I — I 
mode  (directly  from  the  keyboard)  or  from  within  a  BASIC 

program  as  one  of  the  BASIC  commands.  «    | 

If  you  need  to  "pass"  information  from  BASIC  to  ML,  it  is  I — I 
easiest  to  use  integer  numbers  and  just  POKE  them  into  some 

predetermined  ML  variable  zone  that  you've  set  aside  and  ,    j 

noted  on  your  notepad.  Then  just  SYS  to  your  ML  routine,  ! — } 
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STOP 


which  will  look  into  the  set-aside,  POKEd  area  when  it  needs 
the  values  from  BASIC. 

If  you  are  not  going  between  BASIC  and  ML,  you  can 
start  (RUN)  your  ML  program  from  within  the  built-in  mon- 
itor. To  enter  the  monitor,  press  F8.  To  run  an  ML  program 
from  within  the  monitor,  type  G  2000  (that's  address  8192  in 
decimal;  this  presumes  that  you've  either  loaded  in  your  ML 
program  at  that  address  or  have  just  assembled  one  there). 

The  128  expects  to  encounter  a  BRK  instruction  to  end  the 
run  and  return  control  to  the  monitor. 

SAVE 

When  you  save  a  BASIC  program,  the  computer  automatically 
handles  it.  The  starting  address  and  the  ending  address  of 
your  program  are  calculated  for  you.  In  ML,  you  must  know 
the  start  and  end  address.  From  the  monitor,  you  type  S,  then 
the  name  of  your  program,  then  8  for  disk  or  1  for  tape,  the 
starting  address,  and  the  ending  address.  All  these  items  are 
separated  by  commas: 

S  "FILENAME",8,2000,2010 

(Note  that  these  addresses  are  in  hex.  The  addresses  are  8192 
and  8208,  in  decimal,  but  you  must  use  hex  from  the  monitor 
unless  you  specify  otherwise.  See  Chapter  3  for  more  infor- 
mation about  the  monitor.)  For  more  information  about  BSAVE 
and  BLOAD,  the  ML  save  and  load  routines  in  BASIC,  please 
see  your  User's  Guide. 

Saving  object  code  is  automatic  with  LADS;  if  you  use  the 
.D  NAME  pseudo-op,  LADS  will  automatically  save  your  ML 
program  after  it  has  finished  assembling  it.  To  see  how  to  save 
and  load  from  within  your  ML  programs — to  write  ML  which 
itself  saves  and  loads  files — please  refer  to  the  Openl  sub- 
program of  LADS  in  Appendix  D. 


STOP 

BRK  (or  an  RTS  with  no  preceding  JSR)  throws  you  back  into 
/    1  the  monitor  mode  after  running  an  ML  program.  BRK  is  most 

often  used  for  debugging  programs  because  you  can  set 
"breakpoints"  in  the  same  way  that  you  would  use  STOP  to 
j    I  examine  variables  when  debugging  a  BASIC  program. 
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SYS 

This  is  BASIC'S  way  of  using  a  piece  of  ML  code,  an  ML  rou- 
tine, as  a  subroutine.  The  only  difference  between  SYS  and 
GOSUB  is  that  the  computer  is  alerted  to  the  fact  that  it  needs 
to  switch  mental  gears:  The  next  series  of  instructions  will  be 
ML.  In  other  words,  the  computer  shouldn't  try  to  interpret 
what  it  finds  at  the  SYS  address  as  more  BASIC  instructions. 
Later,  when  it  comes  upon  an  RTS  instruction  in  the  ML  pro- 
gram which  was  not  matched  by  a  previous  JSR  instruction,  it 
will  then  revert  to  the  BASIC  program  and  pick  up  where  it 
left  off,  following  the  SYS  instruction. 

There  are  times  when  you  want  to  write  in  ML  and  use  it 
as  a  subroutine  for  a  BASIC  program.  This  can  greatly  speed 
up  the  execution  of  the  BASIC  program.  To  put  an  ML  pro- 
gram in  RAM  where  it  will  be  safe  from  BASIC'S  dynamic 
variable  storage  (where  it  won't  be  overwritten  by  BASIC), 
you  lower  the  "top-of-memory"  pointer  ($39,3A)  to  create 
some  space  in  high  RAM  of  which  the  computer  is  "un- 
aware." This  pointer  contains  the  address  (in  the  usual 
LSB,MSB  format  discussed  earlier)  beyond  which  BASIC  is 
forbidden  to  intrude.  If  you're  going  to  use  only  one  page  of 
memory  (256  bytes),  just  DEC  #3A  which  has  the  effect  of 
making  it  point  256  bytes  lower  than  it  normally  would.  This 
pointer  affects  bank  1. 

After  resetting  this  pointer,  you  are  free  to  load  in  your 
ML  program  into  the  now-safe  RAM  between  where  the 
pointer  points  and  the  true  highest  RAM  byte  in  your 
computer. 

Short  ML  routines  can  always  be  stored  in  the  page  be- 
tween $B00  and  $BFF  without  any  special  preliminaries. 
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String  Handling 
ASC 

In  BASIC,  this  will  give  you  the  number  of  the  ASCII  code  t ) 

which  stands  for  the  character  you  are  testing.  ?ASC("A")  will 

result  in  a  65  being  displayed.  There  is  never  any  need  for  this  , 

in  ML.  If  you  are  manipulating  the  character  A  in  ML,  you  are  j ) 

using  ASCII  already.  In  other  words,  the  letter  A  is  65  in  ML 
programming.  The  Commodore  ASCII  code  isn't  standard 
ASCII;  it  stores  character  symbols  in  some  nonstandard  ways, 
so  you  will  need  to  write  a  special  program  to  be  able  to 
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translate  to  standard  ASCII  if  you  are  using  a  modem  or  some 
other  peripheral  which  uses  true  ASCII.  Appendix  G  lists  both 
Commodore  ASCII  and  true  ASCII. 


CHR$ 

This  is  most  useful  in  BASIC  to  let  you  use  characters  which 
I    (  cannot  be  represented  within  normal  strings,  will  not  show  up 

on  your  screen,  or  cannot  be  typed  from  the  keyboard. 

For  example,  if  you  have  a  printer  attached  to  your  com- 
puter, you  could  send  CHR$(13)  to  it,  and  it  would  perform  a 
carriage  return.  The  correct  numbers  which  accomplish  various 
things  sometimes  differ,  though  decimal  13 — an  ASCII  code 
standard — is  nearly  universally  recognized  as  carriage  return, 
and  the  128  uses  this  convention,  too. 

Or,  you  could  send  the  combination  CHR$(27)  CHR$(8), 
and  the  printer  would  backspace. 

There  is  no  real  use  for  CHR$  within  ML.  If  you  want  to 
specify  a  carriage  return,  just  LDA  #13.  In  ML,  you  are  not 
limited  to  the  character  values  which  can  appear  onscreen  or 
within  strings.  Any  value  can  be  dealt  with  directly. 

LEFTS 

As  usual  in  ML,  you  are  in  charge  of  manipulating  data.  Here's 
one  way  to  extract  a  certain  "substring"  from  the  left  side  of  a 
string  as  in  the  BASIC  statement  LEFT$(X$,5): 

2000    LDY  #$5 

2002    LDX  #$0         Use  X  as  the  offset  for  buffer  storage. 
2004    LDA  $1000,Y   The  location  of  X$. 

2007    STA  $4000,X   The  "buffer,"  or  temporary  storage  area,  for 
the  substring. 


200A   INX 
200B    DEY 
200C   BNE  $2004 


LEN 

jj  In  some  cases,  you  will  already  know  the  length  of  a  string  in 

ML.  One  of  the  ways  to  store  and  manipulate  strings  is  to 
know  beforehand  the  length  and  address  of  a  string.  Then  you 

j|  could  use  the  subroutine  given  for  LEFTS,  above.  More  com- 

monly, though,  you  will  store  your  strings  with  delimiters  (ze- 
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ros)  at  the  end  of  each  string.  To  find  out  the  length  of  a  j    j 

certain  string:  ' — ' 

2000    LDY  #$0 

2002  LDA  $1000,Y   The  address  of  the  string  you  are  testing.  I     I 

2003  BEQ  $2009       Remember,  if  you  LDA  a  zero,  the  zero  flag  is  — ' 

set.  So  you  don't  really  need  to  use  a  CMP  #0 

here  to  test  whether  you've  loaded  the  zero  i     i 

delimiter.  1 — I 

2005  INY 

2006  BNE  $2002       We  are  not  using  a  JMP  here  because  we  as- 

sume that  all  your  strings  are  less  than  256 
characters  long. 

2008  BRK  If  we  still  haven't  found  a  zero  after  256  INYs, 

we  avoid  an  endless  loop  by  just  BRKing  out 
of  the  subroutine. 

2009  DEY  The  LENgth  of  the  string  is  now  in  the  Y 

register. 

We  had  to  DEY  at  the  end  because  the  final  INY  picked 
up  the  zero  delimiter.  So,  the  true  count  of  the  LENgth  of  the 
string  is  one  less  than  Y  shows,  and  we  must  DEY  one  time  to 
make  this  adjustment. 

MID$ 

To  extract  a  substring  which  starts  at  the  fourth  character  from 
within  the  string  and  is  five  characters  long — MID$(X$,4,5): 

2000    LDY  #$5         The  size  of  the  substring  we're  after. 
2002    LDX  #$0         X  is  the  offset  for  storing  the  substring. 

2004  LDA  $1003,Y   To  start  at  the  fourth  character  from  within  the 

X$  located  at  $1000,  simply  add  three  to  that 

address.  Instead  of  starting  our  LDA,Y  at 

$1000,  skip  to  $1003.  This  is  because  the  first  ,     , 

character  is  not  in  position  1.  Rather,  it  is  at  1_J 

the  zeroth  position,  at  $1000. 

2007  STA  $4000,X   The  temporary  buffer  to  hold  the  substring. 

200A  INX  i) 

200B    DEY 
200C   BNE  $2004 

M 

RIGHTS  ' 

This,  too,  is  complicated  because  normally  we  do  not  know  ,    / 

the  LENgth  of  a  given  string.  To  find  RIGHT$(X$,5)  if  X$  LJ 
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starts  at  $1000,  we  should  find  the  LEN  first  and  then  move 
the  substring  to  our  holding  zone  (buffer)  at  $4000: 

2000  LDY  #$0 

2002  LDX   #$0 

2004  LDA  $1000,Y 

2007  BEQ  $200D 

2009  INY 

200A  JMP   $2004 

200D  TYA 


The  delimiting  zero  is  found. 


200E 
200F 


SEC 
SBC 


#$5 


2011     TAY 


2012  LDA  $1000,Y 

2015  BEQ  $201E 

2017  STA  $4000,X 

201A  INX 

201B  DEY 

201C  BNE  $2012 

201E  RTS 


Put  LEN  into  A  so  that  we  can  subtract  the 

substring  size  from  it. 

Always  set  carry  before  any  subtraction. 

Subtract  the  size  of  the  substring  you  want  to 

extract. 

Put  the  offset  back  into  Y,  now  adjusted  to 

point  to  five  characters  from  the  end  of  X$. 

We  found  the  delimiter,  so  end. 
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TAB 

This  formatting  instruction  moves  you  to  a  specified  column 
on  a  given  line.  TAB  10  moves  you  ten  spaces  from  the  left 
side  of  the  screen. 

In  ML,  you  have  more  direct  control  over  what  happens: 
You  would  just  add  or  subtract  the  amount  you  want  to  TAB 
over  to.  If  you  were  printing  to  the  screen  and  wanted  ten 
spaces  between  A  and  B  so  it  looked  like  this: 

A  B 

you  could  write: 

2000  LDA  #$41  A 

2002  STA  $0400  Screen  RAM  address 

2005  LDA  #$42  B 

2007  STA  $040A  You've  added  ten  to  the  target  address. 

Alternatively,  you  could  add  ten  to  the  Y  offset  (this  is 
LADS  format): 

10  SCREEN  =  $0400 
100  LDY  #0:LDA  #"A:STA  SCREEN, Y:LDY  #10:LDA  #"B:STA 
SCREEN,Y 


185 


TAB 


LJ 
U 


An  even  simpler  LADS  method  uses  the  +  pseudo-op  to  )    j 

add  whatever  amount  you  wish  to  a  label:  ( 

10  SCREEN  =  $0400 
100  LDA  #"A:STA  SCREEN:STA  SCREEN +10  I     { 

As  an  example,  we  are  writing  to  the  screen  here,  but  in 
practice,  you  would  print  to  the  screen  using  $FFD2  as  de- 
scribed below.  The  examples  above,  using  Y  as  an  offset,  are  ' | 

more  applicable  to  storing,  say,  items  in  a  database  or  printing 
hardcopy. 

Nonetheless,  if  you  are  printing  out  many  columns  of 
numbers  and  need  a  subroutine  to  space  your  printout  cor- 
rectly, you  might  want  to  use  a  subroutine  which  will  add  ten 
to  the  Y  offset  each  time  you  call  the  subroutine: 

5000  TYA 

5001  CLC 

5002  ADC  #10 

5004  TAY 

5005  RTS 

This  subroutine  directly  adds  ten  to  the  Y  register  when- 
ever you  JSR  $5000.  However,  it's  more  typical  to  rely  on 
$FFD2  for  screen  printing  since  it  will  keep  track  of  the  cursor 
position  for  you.  Just  LDA  with  whatever  character  you  want 
printed  and  then  JSR  $FFD2,  and  it  will  be  printed  at  the  next 
available  space. 

You  can  see  that  moving  over  ten  spaces  could  be  accom- 
plished by  LDA  #32:JSR  $FFD2  performed  ten  times.  The  32 
is  the  blank  character.  However,  here,  too,  there  is  a  more 
practical  method. 

Anything  you  can  print  from  BASIC  you  can  print  from  ML. 
So,  all  the  cursor  control  characters  can  be  printed,  CLR  ,     , 

screen,  backspace,  anything.  Most  control  characters  can  be  < 1 

entered  into  LADS  directly  by  typing  #"c  where  c  is  the  con- 
trol code  you  desire: 

5000  LDA  #"c 

5001  JSR    $FFD2 

Alternatively,  you  can  put  the  actual  Commodore  ASCII  j    I 

value  into  the  accumulator  prior  to  JSR  $FFD2.  One  way  to 
find  out  the  ASCII  value  to,  for  example,  clear  the  screen,  you 
could  go  to  BASIC  and  type  CHR$("  ")  to  get  it.  There  is  a 
complete  list  of  Commodore  128  ASCII  in  Appendix  G.  Here 
is  a  list  of  the  control  characters: 
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Dec     Hex     Uppercase/Graphics  Set    Lowercase/Uppercase  Set 


2 

02 

underline  on1 

5 

05 

white 

7 

07 

bell  tone2 

9 

09 

tab2 

10 

0A 

linefeed2 

13 

0D 

RETURN 

14 

0E 

switch  to  lowercase 

15 

OF 

flash  on1 

17 

11 

cursor  down 

18 

12 

reverse  on 

19 

13 

home 

20 

14 

delete 

24 

18 

TAB  set/clear2 

27 

IB 

ESCape 

28 

1C 

red 

29 

ID 

cursor  right 

30 

IE 

green 

31 

IF 

blue 

32 

20 

space 

129 

81 

orange3 
dark  purple1 

130 

82 

underline  off1 

142 

8E 

switch  to  uppercase 

143 

8F 

flash  off1 

144 

90 

black 

145 

91 

cursor  up 

146 

92 

reverse  off 

147 

93 

clear  screen 

148 

94 

insert 

149 

95 

brown3 
dark  yellow1 

150 

96 

light  red 

151 

97 

dark  gray3 
dark  cyan1 

152 

98 

medium  gray 

153 

99 

light  green 

154 

9A 

light  blue 

155 

9B 

light  gray 

156 

9C 

purple 

157 

9D 

cursor  left 

158 

9E 

yellow 

159 

9F 

cyan 

Notes 

1.  80-column  display  only 

2.  128  mode  only 

3.  40-column  display  only 
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The  128  Environment 


Let's  take  a  tour  of  some  of  the  capabilities  of  this  potent  ma- 
chine. We'll  discover  switches  and  modes  that  you  can  tap 
which  will  turbocharge  your  ML  programs. 

Versatile  Escapes 

First  off,  your  ML  programs  can  control  the  screen  by  invoking 
the  ESCape  key  sequences. 

Do  you  need  to  delete  the  current  line,  the  line  whereon 
the  cursor  sits?  From  BASIC,  you  would  hit  the  ESC  key,  let  it 
go,  then  type  D.  To  do  this  from  within  an  ML  program: 

LDA  #"D:JSR  $C01E 

$C01E  is  a  subroutine  which  activates  the  escape  sequences. 
You  must  be  in  bank  15  for  this  to  work.  If  your  ML  program 
is  going  to  utilize  built-in  routines  like  this,  you  must  either 
switch  in  bank  15  at  the  start  of  your  program  and  leave  it  ac- 
tive (as  does  LADS)  or  switch  it  in  just  before  you  access  a 
subroutine  like  the  one  at  $C01E. 
You  switch  in  bank  15  by: 

LDA  #0:STA  $FF00 

This  is  the  first  thing  LADS  does  prior  to  assembling  your 
source  code  because  LADS  uses  a  number  of  built-in  ROM 
routines. 

Here  is  a  list  of  the  other  escape  sequences;  there's  one 
for  every  letter  of  the  alphabet.  To  use  them,  just  replace  the 
D  in  the  example  above  with  the  appropriate  letter. 

A  Turn  on  autoinsert  mode 

B  Current  cursor  position  becomes  bottom  of  screen  window 

C  Turn  off  autoinsert  mode 

D  Delete  the  line  where  the  cursor  is 

E  Make  cursor  not  flash 

F  Make  cursor  flash 

G  Enable  beep  sound 

H  Prevent  beep  from  sounding 

I  Insert  line 

J  Move  cursor  to  the  start  of  the  current  line 

K  Move  cursor  to  the  end  of  the  current  line 

L  Permit  scrolling 
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M  Prevent  scrolling  )     I 

N  Make  screen  white-on-black  (80-column  screen  only)  * — ' 

O  Turn  off  insert,  reverse,  or  quote  modes 

P  Erase  from  cursor  to  the  start  of  the  current  line 

Q  Erase  from  cursor  to  the  end  of  the  current  line 

R  Turn  on  black-on-white  mode  (80-column  screen  only) 

S  Change  to  square  cursor  (80-column  screen) 

T  Current  cursor  position  becomes  top  of  screen  window  ] j 

U  Change  to  underline  cursor  (80-column  screen) 

V  Cause  scroll  upward 
W  Cause  scroll  downward 

X  Switch  between  a  40-  or  80-column  TV  monitor 

Y  Make  TAB  every  eight  columns 
Z  Remove  all  TABs 

@  Clear  the  screen  from  the  cursor  to  the  bottom 

Many  Memories 

The  128  has  a  total  of  16  memory  configurations,  called  banks. 
Each  bank  is  64K  large,  but  that  doesn't  mean  that  the  128  has 
16  separate  64K  blocks  of  memory.  Rather,  the  banks  are  just 
different  64K  selections  from  the  smorgasbord  of  RAM,  ROM, 
and  input/output  chips  in  the  computer.  Two  banks,  0  and  1, 
are  mostly  RAM,  and  you  can  do  with  them  what  you  will — 
the  RAM  in  each  bank  comes  from  a  separate  64K  block  of 
RAM.  Other  banks  are  mixtures  of  RAM  and  ROM.  Special 
locations  like  low  memory  and  $FFD0  and  other  registers  are 
common  to  all  banks  so  that  communication  is  possible  be- 
tween the  banks  (something  has  to  be  unvarying). 

How  are  these  banks  best  visualized?  Clearly  they  aren't 
all  there  all  the  time.  You  are  always  only  "in"  one  bank  at  a 
time.  You  might  think  of  it  as  if  you  are  in  charge  of  lighting  a 
play  and  you've  got  a  box  with  16  buttons,  one  for  each  bank, 
labeled  0  through  15. 

Onstage,  there  are  16  different  performers,  each  with  dif- 
ferent talents  and  different  shapes  (although  as  you  can  see  in  \    \ 
the  list  of  banks  above,  there  are  some  which  look  like  the                   ' — i 
others  in  places).  In  any  case,  when  the  play  starts,  you  can 
turn  a  spotlight  on  any  performer  you  wish.  But,  the  rule  is  t    j 
that  only  one  performer  can  be  lit  at  a  time.  So,  if  you  turn  on  l — ' 
bank  0,  you  are,  in  effect,  turning  the  light  off  one  other  bank, 
the  one  previously  lit.  i    j 

In  other  words,  you're  confined  to  serial,  not  parallel,  * — ' 

lighting  effects.  However,  you  can  be  very  fast  with  a  series  of 
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switches.  You  can  even  switch  between  banks  so  quickly  that 
the  illusion  is  created  that  more  than  one  is  active  at  once.  By 
using  JSR,  JMP,  CMP,  LDA,  and  STA  LONG  commands  (see 
Chapter  11),  you  can  access  distant  banks  without  even  explic- 
itly switching  out  of  your  home  bank.  The  lighting  will  flicker 
imperceptibly  for  the  briefest  moment  when  you  use  one  of 
the  LONG  Kernal  routines. 

Memory  in  the  Monitor 

When  in  the  monitor  (via  F8  directly  from  BASIC  mode  or  a 
BRK  instruction  that  stops  an  ML  program  in  progress),  you 
can  save,  load,  modify  memory,  and  many  other  things  (see 
Chapter  3).  Normally,  you  use  four-character  hex  numbers  to 
indicate  where  you  want  things  to  happen: 

M0B00 

Or  you  can  leave  off  leading  zeros: 
MB00 

followed  by  RETURN  will  show  you  what's  in  the  memory 
locations  following  address  $B00  in  bank  0.  Bank  0  is  the  de- 
fault when  you  just  give  the  monitor  a  number  between  0  and 
FFFF  (0-65535  decimal).  To  access  other  banks,  you  need  to 
add  a  digit  between  1  and  F  (1-15  decimal)  which  will  put 
you  in  touch  with  any  of  the  banks  you  thus  select.  To  see 
memory  at  BOO  bank  1,  type  M  10B00.  To  see  bank  14,  type 
M  E0B00,  and  so  on,  for  any  of  the  banks.  In  practice,  bank  0, 
bank  1,  and  bank  15  are  the  most  commonly  used.  Bank  0  is 
the  monitor's  default,  bank  1  has  64K  of  free  RAM  memory, 
and  bank  15  puts  all  the  I/O,  BASIC,  and  Kernal  routines  at 
your  disposal.  Here's  what  each  bank  gives  you  when  ref- 
erenced via  the  monitor: 

Bank  Memory  Configuration 

0  RAM  0 

1  RAM  1 

2  RAM  2 

3  RAM  3 

4  Internal  ROM,  RAM  0,  Input/Output  Chips 

5  Internal  ROM,  RAM  1,  Input/Output  Chips 

6  Internal  ROM,  RAM  2,  Input/Output  Chips 

7  Internal  ROM,  RAM  3,  Input/Output  Chips 

8  External  ROM,  RAM  0,  Input/Output  Chips 

9  External  ROM,  RAM  1,  Input/Output  Chips 
A  External  ROM,  RAM  2,  Input/Output  Chips 
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B  External  ROM,  RAM  3,  Input/Output  Chips  )     I 

C  Kernal,  1/2  Internal,  RAM  0,  Input/Output  ( — ' 

D  Kernal,  1/2  External,  RAM  0,  Input/Output 

E  Kernal,  BASIC,  RAM  0,  Character  ROM 

F  Kernal,  BASIC,  RAM  0,  Input/Output 

Its  name  implies  that  the  Commodore  128  has  128K  of 
RAM,  and  you  may  be  wondering  how  that  relates  to  the  \    \ 

information  above.  Interestingly,  the  128  is  actually  designed 
like  a  25  6K  computer  with  only  half  of  its  memory  installed. 
That  memory  is  in  two  separate  64K  blocks,  RAM  0  and  RAM 
1.  The  other  two  blocks,  RAM  2  and  RAM  3,  are  empty.  In 
the  128,  the  phantom  banks  behave  as  mirror  images  of  RAM 
0  and  RAM  1,  respectively.  Thus,  banks  0  and  2  are  identical, 
as  are  banks  9  and  B.  Thus,  until  the  Commodore  256  comes 
along,  the  following  banks  should  not  be  used:  2,  3,  6,  7,  A  and 
B.  Internal  ROM  refers  to  an  empty  socket  inside  the  128  which 
may,  in  the  future,  hold  ROM  chips  with  built-in  software, 
similar  to  the  "productivity  package"  in  the  earlier  Commodore 
Plus/4  model.  External  ROM  refers  to  ROM  in  cartridges 
plugged  into  the  memory  expansion  port.  These  can  be  ignored 
for  now,  so  the  only  banks  you  really  need  to  know  are  0,  1, 
and  15  (and  occasionally  14  if  you  need  access  to  the  character 
ROM — when  designing  custom  character  sets,  for  example). 

If  you  use  some  BASIC  ROM  routines,  you'll  need  a  bank 
that  invokes  it.  If  you  want  to  use  the  Kernal  (the  jump  table 
into  operating  system,  BASIC,  and  I/O  routines),  you'll  have 
to  have  that  as  well.  In  sum,  you  should  probably  call  in  bank 
15  at  the  start  of  your  ML  program  and  have  it  all.  You  don't 
put  a  15  into  the  switching  register  to  get  bank  15 — you  put  a 
0  into  it.  LDA  #0:STA  $FF00  will  create  bank  15,  and  you  can 
then  freely  access  any  routines  you  might  need;  you'll  have 
the  full  complement  of  Commodore  routines  at  your  disposal. 
If  you  need  more  RAM,  switch  in  and  out  of  bank  1.  (Don't 
worry  why  0  calls  in  bank  15;  we'll  explain  forthwith.)  But 
remember  that  the  RAM  portion  of  bank  15  comes  from  the 
same  place  as  bank  0,  the  RAM  0  block.  That  is,  address 
$2000  in  bank  0  and  $2000  in  bank  15  both  refer  to  the  same 
memory  location.  If  you  put  a  routine  at  $2000  in  bank  0,  then 
try  to  put  another  routine  at  that  address  in  bank  15,  you'll 
overwrite  the  original  routine.  i    { 

Or,  best,  use  the  long-distance  JSR,  CMP,  LDA,  and  so  i — ' 

on,  special  features  which  can  quickly  reach  outside  the  cur- 
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rent  bank.  There  is  a  way  to  go  into  other  banks  without 
switching.  We'll  get  to  that  soon.  For  most  ML,  just  remember 
that  you'll  want  to  set  bank  15  as  the  environment.  And,  a 
good  place  to  store  things  is  in  the  64K  RAM  available  in  bank 
1.  The  other  banks  are  only  very  rarely  useful  for  most  ML 
programming. 

Manipulating  Memory 

To  understand  how  the  128  organizes  its  memory,  you  must 
visualize  that  the  8502  chip  can  address  only  64K  of  memory 
at  any  given  time.  Any  single  instruction  can  only,  for  ex- 
ample, LDA  65535  or,  in  hex,  LDA  $FFFF.  You  cannot  LDA 
higher.  Zero  to  65535  is  the  range  of  possible  addressing  for 
an  eight-bit  chip. 

How  then  is  it  possible  to  call  this  the  128  and  say  that 
you  can  use  128K  of  RAM  for  your  programming? 

The  answer  is  that  the  computer  has  a  facility  for  switch- 
ing between  those  zones  of  memory  called  banks.  When  you're 
programming  in  BASIC,  your  program  can  reside  in  one  64K 
area  of  memory  while  its  variables  reside  in  another  64K  area. 
In  ML,  you  can  cause  banks  to  be  switched  in  and  out  of  range 
of  the  chip.  This  switching  is  accomplished  by  storing  different 
numbers  into  location  $FF00. 

There  are  some  considerations.  It  would  be  ungainly  to 
keep  switching  whole  banks  when  you  only  wanted  to  use, 
say,  bank  1  as  storage  space.  The  easier  way  to  access  this 
bank  is  to  use  special  LDA  and  STA  instructions  which  can 
reach  into  it  without  your  switching  banks  in  your  program. 
We'll  get  to  these  special  instructions  in  a  minute. 

When  you  turn  on  the  computer,  it  defaults  to  bank  0 
RAM.  However,  if  you  are  programming  in  ML  and  intend  to 
make  use  of  the  Kernal,  I/O,  and  BASIC  routines  (and  most 
ML  programs  do),  you'll  want  to  switch  to  bank  15  and  stay 
there.  Bank  15  is  the  normal  environment  for  ML  pro- 
grammers because  it  gives  you  some  RAM,  but  it  also  provides 
access  to  all  the  important  ROM  routines,  too.  LADS  switches 
in  bank  15  right  at  the  start  (see  the  Eval  subprogram  in 
Appendix  D).  You  switch  in  bank  15  by  LDA  #0:STA  $FF00, 
and  that's  it.  Thereafter,  unless  you  put  something  else  into 
$FF00,  you'll  be  in  bank  15,  and  all  BASIC'S  routines  and  the 
Kernal  and  I/O  routines  will  be  at  your  disposal. 
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Obviously,  you  couldn't  switch  banks  if  all  64K  always  \    | 

switched  when  you  changed  banks.  $FF00,  for  example,  has  to  V~J 

be  available  to  any  bank.  It  can't  change.  Neither,  for  other 
reasons,  can  zero  page  change.  You  can  count  on  these  loca-  )    j 

tions  to  be  common  to  any  bank.  But  we're  programming  in  *--* 

ML,  and  we're  not  concerned  here  with  banks  which  involve 
CPM,  cartridge  memory,  or  such.  So,  we  need  only  worry  j    / 

about  bank  15,  our  usual  configuration,  and  banks  0  and  1  '—-' 

wherein  we'll  find  lots  of  RAM  with  which  to  make  good  use. 

How  can  you  store  something  in  bank  1  RAM,  then  call 
in  bank  15  with  all  its  ROM?  Won't  the  heavy  information  in 
bank  15  crush  or  cover  over  what  you  put  into  bank  1?  No. 
bank  1  really  is  a  different  memory  area;  you  just  can't  access 
it  at  the  same  time  that  you  access  bank  15  (except  for  the 
memory  zones  they  have  in  common).  So,  STA  LONG  to  bank 
1  while  you're  in  bank  15.  The  things  you  STA  will  still  be 
there  when  you  go  to  LDA  LONG  or  when  you  switch  banks. 

Coming  In  from  the  Keyboard 

If  you  need  to  test  keys  being  pressed,  you'll  have  to  ask  loca- 
tion $D4  (212  decimal).  Unhappily,  this  location  does  not 
yield  the  ASCII  code.  Carriage  return  is  not  13.  The  letter  A  is 
not  65.  It's  another  code  altogether,  the  "keyboard  matrix 
code."  You  don't  need  to  deal  with  this.  If  you  want  your  ML 
program  to  detect  a  particular  key  being  pressed,  find  out  its 
"matrix  code"  by  running  this  simple  BASIC  program: 

10  PRINT  PEEK(212);:GOTO  10 

and  while  it  runs,  press  the  key  you're  interested  in.  The  num- 
bers on  the  screen  will  be  the  code  for  that  key.  Then  you  can: 

LDA  212:CMP  #whatever  code:BEQ  FOUNDIT  ,     ( 

to  handle  a  case  where  some  particular  key  was  pressed.  Notice  '    ' 

that  while  no  key  is  pressed,  the  number  88  is  always  in  ad- 
dress 212.  That's  useful.  You  can  see  if  any  key  is  pressed  by:  \    j 

LDA  212:CMP  #88:BEQ  NOKEY 

and  continue  on  with  your  program  since  the  user  hasn't  ,     . 

touched  the  keyboard.  L_j 

By  the  way,  the  letter  A  is  10,  and  the  carriage  return  key 

is  1  in  the  128's  keyboard  matrix  code.  Don't  worry  about  ,    , 

what  the  matrix  means  or  how  it  is  calculated.  Just  run  the  lit-  | 1 

tie  BASIC  program  above  if  you  want  to  pause  your  space 

Li 
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\    [  invaders  game  when  the  player  holds  down  the  P  key.  It'll  tell 

you  what  P  sticks  into  location  212  and  can  CMP  for  it  and 
JSR  to  a  subroutine  that  pauses  until  any  other  key  is  pressed 

P~j  (when  212  contains  something  besides  the  number  88.) 

The  Speed  Switch 

!*■  One  of  the  most  exciting  and  valuable  features  of  the  128  is 

the  fact  that  you  can  make  the  128  run  twice  as  fast  as  nor- 
mal— go  from  1  to  2  megahertz.  The  speed  is  controlled  by 
the  register  at  $D030.  It  normally  contains  $FC.  If  you  LDA 
#$FF:STA  $D030,  you  switch  on  the  turbocharger  and  things 
only  take  half  as  long  to  compute.  A  40-column  display  will 
blank  out  during  this  speedup.  You  shouldn't  speed  things  up 
during  access  to  disk  or  printer  or  tape,  but  it's  well  worth 
using  in  other  circumstances. 

LADS  uses  this  speed  switch.  For  example,  when  using  a 
1571  disk,  LADS  can  assemble  a  large  program,  72K  of  source 
code,  in  two  minutes,  25  seconds.  Pass  one  takes  55  seconds; 
pass  two  takes  90  seconds.  These  measurements  were  taken 
with  LADS  assembling  itself. 
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Built-in  Routines 


Commodore  machines,  since  the  start,  have  made  a  sensible 
provision  for  upgrading  software  after  the  arrival  of  a  new 
model.  Because  many  programmers  will  want  to  access  the 
canned  ROM  routines  like  PRINT  for  their  own  purposes,  it 
would  be  much  easier  for  software  manufacturers  and  pro- 
grammers in  general  if  the  addresses  of  the  most  popular 
ROM  routines  were  to  remain  stable.  Commodore  has  made  a 
provision  so  that  this  will  happen. 

In  the  original  Commodore  PET,  JSR  $FFD2  printed  the 
character  in  the  accumulator.  In  the  128,  Commodore's  latest 
machine,  it  is  the  same.  There  is  a  whole  list  of  such  ad- 
dresses, high  up  in  ROM  memory,  which  has  remained  trust- 
worthy throughout  the  years  and  has  simplified  the  job  of 
transporting  software  when  new  models  and  new  machines 
are  introduced.  This  list  is  called  the  Kernal. 

The  Kernal  list  is  a  series  of  JMP  $NNNN  instructions. 
The  NNNN  will  point  to  the  actual  address,  in  that  particular 
machine,  where,  say,  PRINT  is  really  accomplished.  You  don't 
need  to  bother  with  the  NNNN  when  using  the  Kernal,  just 
JSR  to  the  Kernal  routine  and  your  program  will  be  directed  to 
the  appropriate  ROM  address.  Here  are  the  useful  Kernal 
routines  for  the  128. 

You  should  be  in  bank  15  to  access  the  128's  Kernal 
routines.  LDA  #0:STA  $FF00  will  accomplish  this;  put  it  at  the 
start  of  your  ML  program  if  you're  going  to  be  using  BASIC  or 
Kernal  ROM  routines. 

Set  2,8,1 

$FFBA  establishes  preconditions  for  communication  with  a 
peripheral  by  setting  up  the  file  number,  device  number,  and 
secondary  address.  It  works  together  with  the  next  two 
routines  described  immediately  below.  It  establishes  the  2,8,1 
part  of  BASIC'S  OPEN  2,8,1,  "FILENAME"  and,  thus,  you 
have  accomplished  one  third  of  the  job  of  opening  a  file  (or 
loading  or  saving)  when  you've  JSRed  to  $FFBA.  You  put  the 
file  number  (2,  in  our  example  above)  into  the  accumulator, 
the  device  number  (8,  for  disk,  in  the  example)  into  X,  and  the 
secondary  address  (the  example's  1)  into  Y.  Then  JSR  $FFBA. 

201 


Chapter  1 1 


u 
u 


Here's  how  to  set  things  up  for  an  OPEN  2,8,1:  '    | 

LDA  #2:LDX  #8:LDY  #1:JSR  $FFBA 

To  see  this  (and  the  two  companion  routines  below)  in  ac-  ,    , 

tion,  prior  to  a  LOAD,  see  the  Openl  subprogram  in  LADS  LJ 

(Appendix  D).  If  you  are  calling  the  printer,  use  4,4,255. 

Set  Filename  U 

$FFBD  also  sets  things  up  prior  to  an  OPEN,  SAVE,  or  LOAD. 
This  tells  the  OPEN,  SAVE,  or  LOAD  where  to  find  the  file- 
name for  the  command.  You  put  the  length  of  the  name  into 
the  accumulator,  the  LSB  of  the  name  into  X,  the  MSB  into  Y. 
Then  JSR  $FFBD. 

Here's  how  you  would  establish  the  name: 

LDA  #4:LDX  #<FILENAME:LDY  #>FILENAME:JSR  $FFBD 
FILENAME  .BYTE  "NAME" 

Note  that  if  you  are  communicating  with  the  printer,  there 
will  be  no  filename.  However,  you  should  still  JSR  to  $FFBD, 
but  give  a  zero  as  the  length. 

Set  Bank  Number 

$FF68  is  the  third  precondition  to  opening,  loading,  or  saving. 
It  establishes  which  bank  you  want  to  have  involved  with  the 
I/O.  Do  you  want  to  load  into  bank  1?  Or  save  from  bank  0? 
You  must  tell  the  computer  prior  to  I/O.  Also,  this  routine 
tells  the  computer  which  bank  holds  the  filename  set  up  by  the 
previous  routine  ($FFBD). 

So,  put  the  memory  bank  (1-15)  into  the  accumulator, 
and  the  bank  where  the  filename  is  into  X.  Then  JSR  $FF68. 
See  the  SAVE  routine  in  Openl  in  LADS  to  follow  how  the 
filename  and  bank  are  handled  prior  to  a  save  from  bank  1  \    / 

(even  though  LADS  resides  in  bank  15).  ^ 

OPEN  |    i 

$FFC0  opens  a  file  on  disk  or  tape.  After  you've  performed  'w-~; 
the  three  precondition  JSRs  above,  you  can  just  JSR  $FFC0 

and  start  working  with  it  (pulling  in  or  sending  out  bytes).  To  I     \ 

see  the  four  Kernal  calls  thus  far  described  working  in  concert,  ^ 
please  look  at  the  LOAD  or  SAVE  routine  in  LADS's  Openl 

subprogram.  The  filename  to  which  those  examples  refer  is  I    | 

held  in  the  Tables  subprogram.  ^ 
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p"j  Just  as  in  BASIC,  you  can  also  pass  commands  to  the  disk 

~"  via  OPEN  15,8,15  "VO:",  where  the  item  in  quotes  (set  up  just 

as  if  it  were  a  filename)  instructs  the  disk  to,  in  this  case,  vali- 
fn  date  the  disk. 

CLOSE 

j"— !  $FFC3  closes  a  file.  When  you  want  to  perform  a  CLOSE,  put 

the  file  number  into  the  accumulator  and  JSR  $FFC3.  LADS 
closes  down  files  during  its  shutdown  routine  in  the  Eval  sub- 
program (lines  4390-4540)  just  prior  to  returning  control  of 
the  computer  to  BASIC. 

Note  that  you  don't  need  to  CLOSE  after  LOAD  or  SAVE. 

INPUT# 

$FFC6  establishes  a  channel  to  a  peripheral  for  input.  You  put 
the  file  number  into  the  X  register  and  JSR  $FFC6.  It's  the 
equivalent  of  the  #2  in  INPUT#2,A$.  This  is  used  any  time 
you  want  to  get  a  byte  from  an  already  opened  disk  file.  It 
would  be  followed  by  the  GET  routine  (below).  Without 
establishing  this  channel,  all  input  comes,  by  default,  from  the 
keyboard.  When  you  finish  and  wish  to  restore  the  default 
conditions,  you  must  JSR  to  CLEARCHANNELS  (below). 

OUTPUT# 

$FFC9  establishes  a  channel  to  a  peripheral  for  output.  You 
put  the  file  number  into  the  X  register  and  JSR  $FFC9.  It's 
the  equivalent  of  the  #3  in  PRINT#3,A$.  It's  used  any  time 
you  want  to  send  a  byte  to  an  already  opened  disk  file.  It 
would  be  followed  by  $FFD2,  the  PRINT  routine.  Without 
establishing  this  channel,  all  output  goes,  by  default,  to  the 
screen.  Thus,  for  each  character  that  you  are  printing  to  the 
printer,  you  must  LDA  #4:JSR  $FFC9:LDA  CHARACTERJSR 
$FFD2:JSR  CLEARCHANNELS.  To  see  this  in  action,  see  the 
printer  routines  in  the  second  half  of  the  LADS  Printops 
subprogram. 

Restore  Default  I/O  (Screen  and  Keyboard) 

$FFCC  clears  the  channels  which  were  established  by  the 
preceding  two  routines.  It  restores  the  keyboard  as  the  default 
for  input  and  the  screen  as  the  default  for  output. 
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INPUT  I    i 

$FFCF  is  an  important  routine.  It's  the  equivalent  of  PRINT,  ^ 

but  in  the  other  direction — it  INPUTs  characters  from  the  key- 
board, or,  if  a  file  and  channel  have  been  opened  for  input  j    I 
from  the  disk,  it  pulls  the  next  character  off  the  file,  leaving  it              L""-' 
in  the  accumulator  for  you  to  do  with  as  you  wish  (store  to  a 
buffer,  encode,  look  for  a  particular  key,  and  so  on).  A  disk                  j    I 
file  will  be  read  sequentially,  one  byte  at  a  time,  by  repeatedly             [ — 
JSR  $FFCF  because  the  disk  will  remember  which  was  the  last 
byte  pulled  off  the  file.  Also,  you  can  read  sequential,  pro- 
gram, or  other  kinds  of  files  in  this  fashion.  If  you  haven't 
opened  a  channel  to  a  disk  file,  the  routine  will  read  from  the 
keyboard  until  it  detects  a  carriage  return. 

PRINT 

$FFD2  is  perhaps  the  most  famous  Commodore  Kernal  routine 
and  you'll  use  it  extensively.  It  parallels  the  INPUT  routine 
above,  except  it  PRINTs  characters — it  goes  in  the  other  direc- 
tion; it's  the  O  in  I/O. 

What  you  put  into  the  accumulator  will  be  printed  to  the 
screen,  or  disk  or  printer  (if  you've  opened  files  and  channels 
to  those  devices  as  described  above).  Obviously,  opening  a 
channel  to  print  to  the  keyboard  is  as  useless  as  opening  a 
channel  to  input  from  the  printer.  Some  peripherals  are,  by 
nature,  insensitive  to  input  or  output. 

If  you  intend  to  print  directly  to  the  screen,  you  can  use 
$C00C  which  operates  just  like  $FFD2,  but  is  slightly  faster. 
FFD2  eventually  gets  to  COOC,  but  it  does  a  number  of  things 
first  which  are  unrelated  to  screen  printing. 

A  third  method  of  printing  which  some  people  find  useful 
is  similar  to  immediate  addressing.  You  JSR  $FA1 7,  and  the  i    / 

128  will  look  for  the  message  you  want  printed  immediately  ^ 

following  this  JSR  in  your  code.  You  must  end  the  message  with 
a  zero  to  show  where  it  finishes.  The  computer  will  print  the 
message  and  then  pick  up  the  next  instruction  just  following 
the  embedded  message.  Here's  an  example  which  combines  tra- 
ditional PRINT  with  this  new  method  we're  calling  PRINTIM, 
for  print  immediate: 
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f~]  Program  11-1.  Embedded  PRINT 

10  *=  ?B00 
r— |      20  .S 
L  l      30  .0 

40  ;     EMBEDDED  PRINT 

50  ; 
I )  60  PRINTIM  =  $FA17;   PRINT  IMMEDIATE 

70  PRINT  =  $FFD2 

80  ; 

90  LDA  #0:STA  $FF00;   SET  BANK  15 

100  LDA  #"A:JSR  PRINT;   NORMAL  PRINT 

110  JSR  PRINTIM;         PRINT  WHAT  IMMEDIATELY  FOLLOWS 

120  .BYTE  "BCDEFG": .BYTE  0;  ZERO  DELIMITER  ENDS  MESSAGE 

130  LDA  #"H:JSR  PRINT;   NORMAL  PRINT 

140  RTS 

Although  this  routine  might  at  first  glance  seem  attractive, 
it  is  probably  better  to  cluster  all  your  messages  at  the  end  of 
your  ML  program  as  described  under  PRINT  in  Chapter  9. 
One  reason  is  that  this  is  an  eccentric  method  of  writing  ML 
and  is  possible  with  only  a  few  operating  systems.  You 
couldn't  run  this  on  the  64,  for  instance. 

But  a  more  important  reason  is  that  you  won't  be  able  to 
debug  your  program  as  easily  because  embedded  messages 
will  not,  of  course,  disassemble. 

LOAD 

$FFD5  loads  a  program  file  into  memory.  You  set  it  up  the 
way  you  would  set  up  access  to  a  sequential  file  (described 
above)  by  establishing  the  file  parameters,  the  filename,  and 
the  bank  wherein  the  name  resides  and  the  bank  to  which  you 

t—m (  wish  the  program  loaded.  The  parameters  are  set  as  0,8,1  for 

',_..!  normal  loading: 

LDA  #0:LDX  #8:LDY  #1:JSR  FFBA 

f~|  sets  the  parameters  for  a  LOAD  from  disk.  It  would  be  0,1,1 

for  tape. 

This  routine  will  also  VERIFY.  If,  just  prior  to  JSR  $FFD5, 
f""j  you  put  a  zero  into  the  accumulator,  LOAD  will  take  place. 

Any  other  number  in  the  accumulator  will  cause  a  VERIFY. 

(There  was  an  error  if,  after  JSR  $FFD5,  the  carry  flag  is  set. 
J     j  So  you  can  BCS  to  an  error-handling  routine.  All  disk  or  tape 

access  can  be  tested  in  this  fashion  for  errors.  The  accumulator 

will  contain  an  error  code  as  well.) 
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Following  LOAD,  Y  holds  the  MSB  of  the  ending  address  '    j 

and  X,  the  LSB.  ^ 

To  see  the  steps  involved  in  loading  a  program  file  into 
bank  1,  see  LOAD  in  the  Openl  LADS  subprogram.  In  addi-  (    j 

tion  to  setting  a  zero  into  the  accumulator  (to  LOAD,  not  t^-i 

VERIFY)  just  prior  to  JSR  $FFD5,  you  can  also  put  the  LSB 
into  X,  the  MSB  into  Y  of  a  target  address.  In  this  way,  you  <     | 

can  force  a  LOAD  to  an  address  other  than  that  from  which  * — ' 

the  program  was  originally  saved.  To  trigger  this  forced  load, 
you  must  use  a  secondary  address  of  0;  that  is,  the  value  you 
load  into  the  Y  register  before  you  call  the  routine  to  set  the 
file  parameters  ($FFBA)  must  be  0  instead  of  the  1  shown  in 
the  example  above.  Then: 

LDA  #0;  cause  LOAD 
LDX  #0;  LSB 
LDY  #$80;  MSB 
JSR    $FFD5 

will  cause  the  program  to  be  loaded  at  address  $8000,  regard- 
less of  where  it  was  saved  from.  Normally,  BASIC  programs 
are  saved  from  $1C00. 

SAVE 

$FFD8  saves  a  program  to  disk  or  tape.  It's  quite  similar  to  the 
way  you  load  and  is  illustrated,  like  LOAD,  in  the  LADS 
Openl  subprogram.  Set  the  filename  (see  $FFBD  above);  set 
the  bank  number  (see  $FF68  above);  set  the  file  parameters 
(see  $FFBA  above).  The  accumulator  is  unused  in  this  routine; 

Y  holds  8  for  disk  or  1  for  tape,  and  X,  holding  the  secondary 
address,  is  only  used  for  tape  SAVEs.  Then  load  the  pointer  to 
the  starting  address  of  the  program  you  want  saved  into  the 
accumulator.  There  is  a  pointer  to  the  normal  start  of  BASIC  [__j 
programs  at  $2D,  so,  unless  you  are  saving  something  other 

than  a  BASIC  program,  LDA  #$2D.  Put  the  ending  address 
(there's  a  pointer  at  $2F  holding  this  address)  into  X  (LSB)  and 

Y  (MSB)  and  JSR  $FFD8.  To  establish  the  ending  address:  LDX 
$2F:LDY  $30. 

)     I 
Test  RUN/STOP  Key  ^ 

$FFE1  checks  the  RUN/STOP  key.  If  it's  being  pressed,  the  Z 
flag  will  be  set,  so  you  can  JSR  $FFE1:BEQ  STOPKEYDOWN.  LJ 

This  is  one  way  to  let  the  user  exit  your  ML  program.  See  line 
690  in  the  Eval  subprogram  of  LADS. 
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m        GET 

■  $FFE4  GETs  a  character.  This  is  a  way  to  get  a  keypress  in  the 

Commodore  ASCII  code  from  the  keyboard.  Unlike  polling  loca- 
j-6!  tion  $D4,  where  you  get  the  keyboard  matrix  value  of  a 

-  J  pressed  key,  JSR  $FFE4  leaves  a  printable  ASCII  character 

code  in  the  accumulator.  It  will  return  a  zero  if  no  key  is 
r-i  pressed: 

GETKEY  JSR  $FFE4 

BEQ   GETKEY 

CMP  #13 

BEQ   CARRIAGE 

CMP  #65 

BEQ   CHARA 

CMP  #66:BEQ  CHARB 

CMP  #"C:BEQ  CHARC 

CMP  #"D:BEQ  CHARD 

shows  how  to  accept  input  from  the  user  and  branch  to  appro- 
priate subroutines  depending  on  which  key  the  user  selected. 
You  can  use  this  to  allow  selection  from  a  menu  (CMP  #"1  if 
the  1  key  is  pressed)  or  to  build  your  own  customized  input 
routine  which,  for  example,  might  refuse  to  recognize  any 
numbers  and,  upon  detecting  one,  would  BEQ  GETKEY  to 
wait  for  a  correct  key.  And,  to  make  $FFE4  especially  conven- 
ient, you  can  directly  print  whatever  ASCII  value  is  returned: 

LOOP  JSR  $FFE4;  GET  KEYPRESS 

BEQ  LOOP;  0  MEANS  NO  KEY  WAS  PRESSED,  SO  TRY  AGAIN 

JSR  $FFD2;  ECHO  THE  CHARACTER  TO  SCREEN 

Cursor  Control 

$FFF0  allows  you  to  find  out  where  the  cursor  is  on  the  screen 
or  to  move  it  to  a  different  location.  If  you  are  using  the  128's 
windowing  facility,  the  positions  will  reference  the  start  ad- 
dress of  the  window. 

r™J  The  carry  flag  is  used  to  determine  whether  you  intend  to 

read  or  move  the  cursor.  SEC  if  you  want  to  read.  CLC  if  you 
want  to  move. 

|— ]  To  move  the  cursor  down  three  lines  and  over  five  po- 

sitions, you  first  read  its  position  by  SEC: JSR  $FFF0.  Then, 
you  set  it  up  to  move  down  three  lines  by  INX:INX:INX  and 

|— I  over  five  columns  by  INY:INY:INY:INY:INY  and  CLGJSR 

'  -  $FFF0  to  send  the  cursor  to  its  new  place  on  the  screen.  The 
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carry  will  be  set  if  there  was  an  error,  so  you  can  BCS  ,     . 

ERROROUTINE  after  JSR  $FFF0  to  check.  i_J 

This  routine  has  obvious  applications  for  screen  format- 
ting, TAB,  and  PRINTAT  routines.  It  could  also  be  used  to  ,(    , 

govern  some  kinds  of  games  where  character  graphics  are  on  i i 

the  move  around  the  screen. 

(     i 
The  routines  described  so  far  (except  for  Set  Bank  Number  \ i 

and  Print  Immediate)  are  Commodore  Kernal  routines  and,  there- 
fore, can  be  used  in  64  mode  as  well  as  128  mode.  However,  the 
following  routines  are  new,  created  to  access  some  of  the  features 
unique  to  the  128. 

GO  64 

$FF4D  sends  you  into  64  mode,  with  no  hope  of  returning. 
JMP  to  it  and  you  cannot  regain  control  via  ML.  It's  as  if  you 
typed  GO  64  from  BASIC  and  answered  Y  when  asked  ARE 
YOU  SURE?  The  machine  transforms  itself  into  a  64  and  the 
transformation  cannot  be  reversed  without  resetting  the 
computer. 

Customize  Function  Keys 

$FF65  changes  the  command  available  via  one  of  the  function 
keys.  You  can  customize  a  function  key  to  print  whatever  you 
want  onscreen  and,  if  it's  a  command,  perform  a  carriage  re- 
turn to  activate  the  command.  Function  keys  operate  using  a 
principle  similar  to  the  "dynamic  keyboard"  technique  in  use 
for  years  on  Commodore  computers.  Dynamic  keyboard  refers 
to  stuffing  the  keyboard  buffer  with  the  required  command 
and  then,  when  the  computer  regains  control,  the  buffer  is 
emptied  to  the  screen  just  as  if  the  user  had  typed  in  whatever 
was  in  the  buffer.  This  can,  among  other  things,  cause  a  \^J 

BASIC  program  to  modify  itself  (if  you  include  a  line  number  "~*~" 

at  the  start  of  the  message  and  end  with  a  carriage  return). 

To  program  a  function  key,  you  have  the  accumulator                   |^J 
point  to  a  pointer  in  zero  page  which  has  the  LSB,  MSB,  and 
bank  number  of  the  string  which  you  want  printed  when  the 
function  key  is  pressed.  So,  if  you  set  up:  j J 

FA  00 

FB  30  ,     , 

FCOF  U 

that  would  point  to  a  string  at  $3000  in  bank  15.  Waiting  at 
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j — |  address  3000  might  be  LIST  with  a  carriage  return.  In  LADS, 

'  you  would: 

LDA  #<F8:STA  $FA:LDA  #>F8:STA  $FB:LDA  #15:STA  $FC 
j|  to  set  up  the  pointer  and  have,  at  the  location  we'll  label  F8: 

F8  .BYTE  "LIST":.BYTE  13 

Then,  you  put  the  length  of  your  string  into  Y  which,  in  this 
example,  is  5.  Finally,  put  the  function  key  you  want  to  mod- 
ify into  X  (8,  in  this  example),  and  then  JSR  $FF65.  The  com- 
plete LADS  source  code  to  accomplish  this  is 

LDA  #0:STA  $FF00;  SWITCH  INTO  BANK  15 

LDA  #<F8:STA  $FA:LDA  #>F8:STA  $FB:LDA  #15:STA  $FC;  SET 

UP  POINTER  TO  F8 

LDA  #$FA:LDY  #5:LDX  #8:JSR  $FF65;  CREATE  FUNCTION 

KEY  #8 

F8  .BYTE  "LIST":.BYTE  13 

The  normal  function  keys  are  numbered  1  through  8.  You 
can  also  customize  the  SHIFT-RUN/STOP  key  by  putting  9 
into  X,  or  the  HELP  key  with  a  10  in  X  prior  to  JSRing  (these 
two  keys  cannot  be  changed  via  the  KEY  command  in  BASIC. 
It's  possible  only  in  ML). 

Bank  Number  Code 

$FF6B  lets  you  know  the  proper  code  for  accessing  a  memory 
bank.  You  may  have  noticed  that  you  LDA  #0:STA  $FF00  to 
select  bank  fifteen,  not  bank  zero  as  you  might  expect.  When 
setting  the  $FF00  register,  you  have  to  use  the  code,  but  when 
indicating  a  bank  in  most  other  routines  (far  JSR,  LDA,  etc., 
and  FF65  above)  you  give  the  actual  bank  number. 

If  you  have  a  problem  accessing  a  bank,  it  may  be  that 

|~-J  you  need  to  use  the  bank  code  rather  than  the  bank's  actual 

'    '  number.  In  that  case,  try  LDX  #BANKNUMBER:JSR 

$FF6B:BRK,  and  the  accumulator  will  hold  the  bank  code  for 

r~J  that  bank  number.  To  find  out  what  bank  code  to  store  in 

'    *  $FF00  to  switch  to  bank  14: 

LDX  #14:JSR  $FF6B:BRK 

/    )  and  the  accumulator  will  have  the  answer.  Try  substituting 

that  number  for  the  actual  bank  number  in  your  routine  and 
__  see  if  it  works.  However,  other  than  $FF00  and  some  few  reg- 

/    (  isters  right  above  it,  the  actual  bank  number  will  work  and 

you  needn't  bother  with  any  of  this  special  coding. 

H 
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Long-Distance  Access 

JSR  Long 

$FF6E  will  JSR  to  an  ML  routine  in  a  bank  other  than  the  one 

you're  currently  in.  There  are  several  such  long-distance  j    { 

routines  which  will  be  described  below.  They  use  the  actual  ^ 

bank  number  and  also  set  up  pointers  in  zero  page.  Some 

preparations  are  necessary.  First  we  must  save  the  registers  (    j 

and  the  status  register:  ' — ' 

STA  6:STX  7:STY  8:PHP:PLA:STA  5 

accomplishes  that.  Then  we  announce  that  we  want  to  JSR  to 
bank  1  at  address  $4000: 

LDA  #1:STA  2:LDA  #$40:STA  3:LDA  #0:STA  4 

and  we  can  now  JSR  $FF6E,  and  the  ML  routine  in  bank  1  at 
address  $4000  will  RTS  back  to  our  current  bank  just  like  any 
other  subroutine.  However,  we'll  need  to  mirror  image  the 
save-registers  routine  above  to  restore  stability: 

LDA  5:PHA:LDA  6:LDX  7:LDY  8:PLP 

This  makes  a  JSR  long-distance  nondestructive  to  the  current 
environment,  like  $FFD2.  Registers  and  the  flags  are  un- 
affected by  the  JSR  because  we  saved  and  restored  them. 

JMP  Long 

$FF71  is  a  JMP  long-distance.  It  works  precisely  like  the  JSR 
described  above  except  that,  like  any  JMP,  there  is  no  auto- 
matic return. 

LDA  Long 

$FF74  is  a  long-distance  LDA  (NN),Y  and,  as  with  JSR  long- 
distance described  above,  must  set  up  a  few  things  before  be-  ,    , 
ing  activated.  You  put  the  pointer  to  the  address  in  the  LJ 
accumulator  and  the  bank  number  in  X.  Presumably,  Y  is  be- 
ing used  by  you  as  an  index  as  it  normally  would  be  in  in-  ,    . 
direct  Y  addressing.  l^j 

If  you  want  to  load  the  byte  at  address  $4000  of  bank  1 

(you're  not  in  bank  1  or  you  wouldn't  need  to  load  long-  , 

distance):  i — i 

LDA  #0:STA  $FC:LDA  #$40:STA  $FD;  to  set  up  the  pointer 

LDA  $FC;  to  point  to  the  pointer 

LDX  #1;  point  to  the  bank 

JSR    $FF74;  causes  LDA  ($FC),Y  from  bank  1 
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P]  STA  Long 

$FF77  is  a  long-distance  STA  (NN),Y  and  operates  like  LDA 

described  just  above.  You  put  the  byte  you  want  stored  into 
j~""j  the  accumulator  and  the  bank  number  into  X.  However,  you 

must  also  store  the  pointer  ($FC  in  our  example  below)  into 

$2B9: 
j"~]  First  set  up  the  pointer: 

LDA  #0:STA  $FC:LDA  #$40:STA  $FD:LDA  #$FC:STA  $2B9 

Then  put  the  byte  you  want  stored  into  the  accumulator: 

LDA  #45 

And  put  the  bank  number  into  X: 

LDX#1 

And: 

JSR  $FF77 

Remember  that,  as  always,  Y  is  an  offset,  so  if  it's  not 
holding  a  zero  when  you  JSR  $FF77,  its  value  will  be  added  to 
$4000  to  determine  exactly  where  in  bank  1  the  45  in  the 
accumulator  will  be  stored. 

When  the  .D  pseudo-op  is  invoked  in  LADS,  it  stores  ob- 
ject code  to  bank  1  and  uses  this  long-distance  STA. 

CMP  Long 

$FF7A  compares — CMP  (NN),Y — long-distance.  You  set  up  a 
pointer  in  zero  page  and  store  the  pointer's  address  in  $2C8 
(as  described  above  for  the  long-distance  STA).  Then  you  put 
the  byte  to  be  compared  into  the  accumulator  and  the  bank 
number  into  X.  Y  holds  the  offset,  if  any,  as  is  usual  with  in- 
direct Y  addressing. 
j    |  Then  JSR  $FF7A  and  the  flags  will  be  set  according  to  the 

result  of  the  comparison  as  normal.  You  can  BEQ,  BNE,  BCC, 
BCS  as  you  normally  would  after  a  CMP  test. 
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8502  Instruction  Set 


Here  are  the  56  mnemonics,  the  56  instructions  you  can  give 
the  8502  (or  6502  or  6510)  chip.  Each  of  these  instructions  is 
described  below  in  several  ways:  what  it  does,  what  major 
uses  it  has  in  ML  programming,  what  addressing  modes  it  can 
use,  what  flags  it  affects,  its  opcode  (hex/decimal),  and  the 
number  of  bytes  it  uses  up. 

ADC 

What  it  does:  Adds  byte  in  memory  to  the  byte  in  the 
accumulator,  plus  the  carry  flag  if  set.  Sets  the  carry  flag  if  re- 
sult exceeds  255.  The  result  is  left  in  the  accumulator. 

Major  uses:  Adds  two  numbers  together.  If  the  carry  flag 
is  set  prior  to  an  ADC,  the  resulting  number  will  be  one 
greater  than  the  total  of  the  two  numbers  being  added  (the 
carry  is  added  to  the  result).  Thus,  one  always  clears  the  carry 
(CLC)  before  beginning  any  addition  operation.  Following  an 
ADC,  a  set  (up)  carry  flag  indicates  that  the  result  exceeded 
one  byte's  capacity  (was  greater  than  255),  so  you  can  chain- 
add  bytes  by  subsequent  ADCs  without  any  further  CLCs  (see 
"Multibyte  Addition"  in  Appendix  E). 

Other  flags  affected  by  addition  include  the  V  (overflow) 
flag.  This  flag  is  rarely  of  any  interest  to  the  programmer.  It 
merely  indicates  that  a  result  became  larger  than  could  be  held 
within  bits  0-6.  In  other  words,  the  result  "overflowed"  into 
bit  7,  the  highest  bit  in  a  byte.  Of  greater  importance  is  the 
fact  that  the  Z  flag  is  set  if  the  result  of  an  addition  is  zero. 
Also  the  N  flag  is  set  if  bit  7  is  set.  This  N  flag  is  called  the 
"negative"  flag  because  you  can  manipulate  bytes  thinking  of 
the  seventh  bit  as  a  sign  (+  or  — )  to  accomplish  "signed 
arithmetic"  if  you  want  to.  In  this  mode,  each  byte  can  hold  a 
maximum  value  of  127  (since  the  seventh  bit  is  used  to  reveal 
the  number's  sign).  The  B  branching  instruction's  relative 
addressing  mode  uses  this  kind  of  arithmetic. 

ADC  can  be  used  following  an  SED  which  puts  the  8502 
into  "decimal  mode."  Here's  an  example.  Note  that  the  num- 
ber 75  is  decimal  after  you  SED: 
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SED 
CLC 

LDA  #$75 

ADC  #$05    This  will  result  in  80. 

CLD  Always  get  rid  of  decimal  mode  as  soon  as  you've 

finished. 

Attractive  as  it  sounds,  the  decimal  mode  isn't  of  much 
real  value  to  the  programmer.  LADS  will  let  you  work  in  deci- 
mal if  you  want  to  without  requiring  that  you  enter  the  8502's 
mode.  Just  leave  off  the  $,  and  LADS  will  handle  the  decimal 
numbers  for  you. 

Addressing  modes: 


Name 

Format 

Opcode 

Bytes  Used 

Immediate 

ADC  #15 

$69/105 

2 

Zero  Page 

ADC  15 

$65/101 

2 

Zero  Page,X 

ADC  15,X 

$75/117 

2 

Absolute 

ADC  1500 

$6D/109 

3 

Absolute,X 

ADC  1500,X 

$7D/125 

3 

Absolute,Y 

ADC  1500,Y 

$79/121 

3 

Indirect,X 

ADC  (15,X) 

$61/97 

2 

Indirect,Y 

ADC  (15),Y 

$71/113 

2 

Affected  flags: 

NZCV 

u 


1  { 


u 


AND 

What  it  does:  Logical  ANDs  the  byte  in  memory  with  the 
byte  in  the  accumulator.  The  result  is  left  in  the  accumulator. 
All  bits  in  both  bytes  are  compared,  and  if  both  bits  are  one, 
the  result  is  one.  If  either  or  both  bits  are  zero,  the  result  is 
zero. 

Major  uses:  Most  of  the  time,  AND  is  used  to  turn  bits 
off.  Let's  say  that  you  are  pulling  in  numbers  higher  than  128 
(10000000  and  higher)  and  you  want  to  "unshift"  them  and 
print  them  as  lowercase  letters.  You  can  then  put  a  zero  into 
the  seventh  bit  of  your  "mask"  and  then  AND  the  mask  with 
the  number  being  unshifted: 

LDA  ?  Test  number 

AND#$7F    01111111 

(If  either  bit  is  zero,  the  result  will  be  zero.  So  the  seventh 
bit  of  the  test  number  is  turned  off  here,  and  all  the  other  bits 
in  the  test  number  are  unaffected.) 
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Addressing  modes: 


Name 

Format 

Opcode 

Bytes  Used 

Immediate 

AND  #15 

$29/41 

2 

Zero  Page 

AND  15 

$25/37 

2 

Zero  Page,X 

AND  15,X 

$35/53 

2 

Absolute 

AND  1500 

$2D/45 

3 

Absolute,X 

AND  1500,X 

$3D/61 

3 

Absolute,Y 

AND  1500,Y 

$39/57 

3 

Indirect,X 

AND  (15,X) 

$21/33 

2 

Indirect,Y 

AND  (15),Y 

$31/49 

2 

Affected  flags: 

NZ 

n 


!    ! 


ASL 

What  it  does:  Shifts  the  bits  in  a  byte  to  the  left  by  1. 
This  byte  can  be  in  the  accumulator  or  in  memory,  depending 
on  the  addressing  mode.  The  shift  moves  the  seventh  bit  into 
the  carry  flag  and  shoves  a  zero  into  the  zeroth  bit. 


nn/)A/)/)n 


Bit     Bit     Bit     Bit     Bit     Bit     Bit     Bit 
7       6       5       4       3       2       10 


Major  uses:  Allows  you  to  multiply  a  number  by  2.  Num- 
bers bigger  than  255  can  be  manipulated  using  ASL  with  ROL 
(see  "Multiplication"  in  Appendix  E). 

A  secondary  use  is  to  move  the  lower  four  bits  in  a  byte 
(a  four-bit  unit  is  often  called  a  nybble)  into  the  higher  four 
bits.  The  lower  bits  are  replaced  by  zeros,  since  ASL  stuffs 
zeros  into  the  zeroth  bit  of  a  byte.  You  move  the  lower  to  the 
higher  nybble  of  a  byte  by  ASL  ASL  ASL  ASL. 


Addressing  modes: 

Name 

Accumulator 
Zero  Page 
Zero  Page,X 
Absolute 
Absolute,X 


Format 

ASL 
ASL  15 
ASL  15,X 
ASL  1500 
ASL  1500,X 


Opcode 

$0A/10 

$06/6 

$16/22 

$0E/14 

$lE/30 


Bytes  Used 
1 

2 
2 
3 
3 


Affected  flags:  N  Z  C 
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Addressing  modes: 

Name  Fc 

Relative  B( 

Affected  flags:  None 


Name  Format  Opcode  Bytes  Used 

Relative  BCC  addr.  $90/144  2 


Addressing  modes: 

Name  Fc 

Relative  B( 

Affected  flags:  None 


Name  Format  Opcode  Bytes  Used 

Relative  BCS  addr.  $B0/176  2 


u 
u 


BCC  u 

What  it  does:  Branches  up  to  127  bytes  forward  or  128 
bytes  backward  from  the  address  of  the  following  instruction 

if  the  carry  flag  is  clear.  In  effect,  it  branches  if  the  first  item  j { 

(the  accumulator  contents)  is  lower  than  the  second,  as  in  LDA 
#149:CMP  #150  or  LDA  #15:  SBC  #22.  The  comparison  or 

subtraction  would  clear  the  carry  and,  the  cleared  carry  then  j j 

triggering  BCC,  a  branch  would  take  place. 

Major  uses:  For  testing  the  results  of  CMP  or  ADC  or 
other  operations  which  affect  the  carry  flag.  IF-THEN  or  ON- 
GOTO  type  structures  in  ML  can  involve  the  BCC  test.  It  is 
similar  to  BASIC'S  <  instruction. 


BCS 

What  it  does:  Branches  up  to  127  bytes  forward  or  128 
bytes  backward  from  the  address  of  the  following  instruction 
if  the  carry  flag  is  set.  It  branches  if  the  first  item  (the  accu- 
mulator contents)  is  higher  than  or  equal  to  the  second,  as  in 
LDA  #249:CMP  #150  or  LDA  #85:SBC  #22.  The  comparison 
or  subtraction  would  set  the  carry  and,  the  carry  then  trigger- 
ing BCS,  a  branch  would  take  place. 

Major  uses:  For  testing  the  results  of  LDA  or  ADC  or 
other  operations  which  affect  the  carry  flag.  IF-THEN  or  ON- 
GOTO  type  structures  in  ML  can  involve  the  BCC  test.  It  is                ,     , 
similar  to  BASIC'S  >=  instruction.  1 j 


U 


BEQ  ,    , 

What  it  does:  Branches  up  to  127  bytes  forward  or  128  ' — ' 
bytes  backward  from  the  address  of  the  following  instruction 
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if  the  zero  flag  (Z)  is  set.  In  other  words,  it  branches  if  an  ac- 
tion on  two  bytes  results  in  a  zero,  as  in  LDA  #150:  CMP 
#150  or  LDA  #22:  SBC  #22.  These  actions  would  set  the  zero 
flag,  so  the  branch  would  take  place. 

Major  uses:  For  testing  the  results  of  LDA  or  ADC  or 
other  operations  which  affect  the  carry  flag.  IF-THEN  or  ON- 
GOTO  type  structures  in  ML  can  involve  the  BEQ  test.  It  is 
similar  to  BASIC'S  =  instruction. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Relative  BEQ  addr.  $F0/240  2 

Affected  flags:  None 


BIT 

What  it  does:  Tests  the  bits  in  the  byte  in  memory  against 
the  bits  in  the  byte  held  in  the  accumulator.  The  bytes  (mem- 
ory and  accumulator)  are  unaffected.  BIT  merely  sets  flags. 
The  Z  flag  is  set  as  if  an  accumulator  AND  memory  had  been 
performed.  The  V  flag  and  the  N  flag  receive  copies  of  the 
sixth  and  seventh  bits  of  the  tested  number. 

Major  uses:  Although  BIT  has  the  advantage  of  not  hav- 
ing any  effect  on  the  tested  numbers,  it  is  infrequently  used 
because  you  cannot  employ  the  immediate  addressing  mode 
with  it.  Other  tests  (CMP  and  AND,  for  example)  can  be  used 
instead. 

Addressing  modes: 

Name 
!""""[  Zero  Page 

Absolute 

Affected  flags:  N  Z  V 

n     


Format 

Opcode 

Bytes  Used 

BIT  15 

$24/36 

2 

BIT  1500 

$2C/44 

3 

BMI 

I    I  What  it  does:  Branches  up  to  127  bytes  forward  or  128 

bytes  backward  from  the  address  of  the  following  instruction 
r— ,  if  the  negative  (N)  flag  is  set.  In  effect,  it  branches  if  the  sev- 

J    \  enth  bit  has  been  set  by  the  most  recent  event:  LDA  #150  or 

LDA  #128  would  set  the  seventh  bit.  These  actions  would  set 
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Major  uses:  Testing  for  BASIC  keywords,  shifted  ASCII, 
or  graphics  symbols.  Testing  for  +  or  —  in  signed  arithmetic. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Relative  BMI  addr.  $30/48  2 

Affected  flags:  None 


BNE 

What  it  does:  Branches  up  to  127  bytes  forward  or  128 
bytes  backward  from  the  address  of  the  following  instruction 
if  the  zero  flag  is  clear.  In  other  words,  it  branches  if  the  result 
of  the  most  recent  event  is  not  zero,  as  in  LDA  #150:  SBC 
#120  or  LDA  #128:  CMP  #125.  These  actions  would  clear  the 
Z  flag,  signifying  that  a  result  was  not  zero. 

Major  uses:  The  reverse  of  BEQ.  BNE  means  Branch  if 
Not  Equal.  Since  a  CMP  subtracts  one  number  from  another 
to  perform  its  comparison,  a  zero  result  means  that  they  are 
equal.  Any  other  result  will  trigger  a  BNE  (not  equal).  Like  the 
other  B  branch  instructions,  it  has  uses  in  IF-THEN,  ON- 
GOTO  type  structures  and  is  used  as  a  way  to  exit  loops  (for 
example,  BNE  will  branch  back  to  the  start  of  a  loop  until  a 
zero  delimiter  is  encountered  at  the  end  of  a  text  message). 
BNE  is  like  BASIC'S  <>  instruction. 


Addressing  modes: 

Name  Fc 

Relative  Br 

Affected  flags:  None 


Name  Format  Opcode  Bytes  Used 

Relative  BNE  addr.  $D0/208  2 


BPL 

What  it  does:  Branches  up  to  127  bytes  forward  or  128 
bytes  backward  from  the  address  of  the  following  instruction 
if  the  N  flag  is  clear.  In  effect,  it  branches  if  the  seventh  bit  is 
clear  in  the  most  recent  event,  as  in  LDA  #12  or  LDA  #127. 
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the  N  flag,  signifying  that  a  minus  number  is  present  if  you  are  j    I 

using  signed  arithmetic  or  that  there  is  a  shifted  character  (or  a  ' — ' 
BASIC  keyword)  if  you  are  thinking  of  a  byte  in  terms  of  the 
ASCII  code. 
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These  actions  would  clear  the  N  flag,  signifying  that  a  plus 
number  (or  zero)  is  present  in  signed  arithmetic  mode. 

Major  uses:  For  testing  the  results  of  LDA  or  ADC  or 
other  operations  which  affect  the  negative  (N)  flag.  IF-THEN 
or  ON-GOTO  type  structures  in  ML  can  involve  the  BCC  test. 
It  is  the  opposite  of  the  BMI  instruction.  BPL  can  be  used  for 
tests  of  "unshifted"  ASCII  characters  and  other  bytes  which 
have  the  seventh  bit  off  and  so  are  lower  than  128 
(OXXXXXXX). 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Relative  BPL  addr.  $10/16  2 

Affected  flags:  None 


BRK 

What  it  does:  Causes  a  forced  interrupt.  This  interrupt 
cannot  be  masked  (prevented)  by  setting  the  I  (interrupt)  flag 
within  the  status  register.  If  there  is  a  Break  Interrupt  Vector  (a 
vector  is  like  a  pointer)  in  the  computer,  it  may  point  to  a  res- 
ident monitor  if  the  computer  has  one.  The  PC  and  the  status 
register  are  saved  on  the  stack.  The  PC  points  to  the  location 
of  the  BRK  +  2. 

Major  uses:  Debugging  an  ML  program  can  often  start 
with  a  sprinkling  of  BRKs  into  suspicious  locations  within  the 
code.  The  ML  is  executed,  a  BRK  stops  execution  and  drops 
you  into  the  monitor,  you  examine  registers  or  tables  or  vari- 
ables to  see  if  they  are  as  they  should  be  at  this  point  in  the 
execution,  and  then  you  restart  execution  from  the  breakpoint. 
j    j  This  instruction  is  essentially  identical  to  the  actions  and  uses 

of  the  STOP  command  in  BASIC. 

(— i  Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Implied  BRK  $00/0  1 

|     j  Affected  flags:  Break  (B)  flag  is  set. 


n 
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bvc  Li 

What  it  does:  Branches  up  to  127  bytes  forward  or  128 

bytes  backward  from  the  address  of  the  following  instruction 

if  the  V  (overflow)  flag  is  clear.  J j 

Major  uses:  None.  In  practice,  few  programmers  use 
"signed"  arithmetic  where  the  seventh  bit  is  devoted  to  in- 
dicating a  positive  or  negative  number  (a  set  seventh  bit  j j 

means  a  negative  number).  The  V  flag  has  the  job  of  notifying 
you  when  you've  added,  say,  120  +  30,  and  have  therefore 
set  the  seventh  bit  via  an  "overflow"  (a  result  greater  than 
127).  The  result  of  your  addition  of  two  positive  numbers 
should  not  be  seen  as  a  negative  number,  but  the  seventh  bit 
is  set.  The  V  flag  can  be  tested  and  will  then  reveal  that  your 
answer  is  still  positive,  but  an  overflow  took  place. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Relative  BVC  addr.  $50/80  2 

Affected  flags:  None 


BVS 

What  it  does:  Branches  up  to  127  bytes  forward  or  128 
bytes  backward  from  the  address  of  the  following  instruction 
if  the  V  (overflow)  flag  is  set. 

Major  uses:  None;  see  BVC  above. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Relative  BVS  addr.  $70/112  2 

Affected  flags:  None 


I     f 


CLC  i-J 

What  it  does:  Clears  the  carry  flag  (puts  a  zero  into  it). 

Major  uses:  Always  used  before  any  addition  (ADC).  If  t    j 

there  are  to  be  a  series  of  additions  (multiple-byte  addition),  * — > 
only  the  first  ADC  is  preceded  by  CLC  since  the  carry  feature 

is  necessary.  There  might  be  a  carry,  and  the  result  will  be  in-  t    j 

correct  if  it  is  not  taken  into  account.  ( — - 

The  8502  does  not  offer  an  addition  instruction  without 
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the  carry  feature.  Thus,  you  must  always  clear  it  before  the 
first  ADC  so  that  a  carry  won't  be  accidentally  added. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Implied  CLC  $18/24  1 

Affected  flags:  Carry  (C)  flag  is  set  to  zero. 

CLD 

What  it  does:  Clears  the  decimal  mode  flag  (puts  a  zero 
into  it). 

Major  uses:  This  clears  the  flag  which  forces  the  chip  into 
"decimal  mode."  On  some  computers,  it's  necessary  to  CLD  at 
the  start  of  an  ML  program  because  the  D  flag  can  be  in  an  in- 
determinate state  when  you  SYS  to  your  ML  routine.  How- 
ever, this  isn't  necessary  on  the  128.  Commodore  computers 
thoughtfully  execute  a  CLD  when  first  turned  on  as  well  as 
upon  entry  to  monitor  modes  (PET/CBM  and  128  models) 
and  when  the  SYS  command  occurs. 

For  further  detail  about  the  8502's  decimal  mode,  see  SED 
below. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Implied  CLD  $D8/216  1 

Affected  flags:  Decimal  (D)  flag  is  set  to  zero. 


CLI 

What  it  does:  Clears  the  interrupt-disable  flag.  All  inter- 
rupts will  therefore  be  serviced  (including  maskable  ones). 

Major  uses:  To  restore  normal  interrupt  routine  process- 
ing following  a  temporary  suspension  of  interrupts  for  the 
purpose  of  redirecting  the  interrupt  vector.  For  more  detail,  see 
SEI  below. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Implied  CLI  $58/88  1 

Affected  flags:  Interrupt  (I)  flag  is  set  to  zero. 
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CLV 

What  it  does:  Clears  the  overflow  flag  (puts  a  zero  into  it). 
Major  uses:  None;  see  BVC  above. 

Addressing  modes:  j j 

Name  Format  Opcode  Bytes  Used 

Implied  CLV  $B8/184  1 

Affected  flags:  Overflow  (V)  flag  is  set  to  zero. 


U 


CMP 

What  it  does:  Compares  the  byte  in  memory  to  the  byte 
in  the  accumulator.  Three  flags  are  affected,  but  the  bytes  in 
memory  and  in  the  accumulator  are  undisturbed.  A  CMP  is 
actually  a  subtraction  of  the  byte  in  memory  from  the  byte  in 
the  accumulator.  Therefore,  if  you  LDA  #15:CMP  #15,  the  re- 
sult (of  the  subtraction)  will  be  zero,  and  BEQ  would  be  trig- 
gered since  the  CMP  would  have  set  the  Z  flag. 

Major  uses:  This  is  an  important  instruction  in  ML.  It  is 
central  to  IF-THEN  and  ON-GOTO  type  structures.  In 
combination  with  the  B  branching  instructions  like  BEQ,  CMP 
allows  the  8502  chip  to  make  decisions,  to  take  alternative 
pathways  depending  on  comparisons.  CMP  throws  the  N,  Z, 
or  C  flag  up  or  down.  Then  a  B  instruction  can  branch, 
depending  on  the  condition  of  a  flag. 

Often,  an  action  will  affect  flags  by  itself,  and  a  CMP  will 
not  be  necessary.  For  example,  LDA  #15  will  put  a  zero  into 
the  N  flag  (seventh  bit  not  set)  and  will  put  a  zero  into  the  Z 
flag  (the  result  was  not  zero).  LDA  does  not  affect  the  C  flag. 
In  any  event,  you  could  LDA  #15:  BPL  TARGET,  and  the 
branch  would  take  effect.  However,  if  you  LDA  $20  and  need  1    ( 

to  know  if  the  byte  loaded  is  precisely  $0D,  you  must  CMP  ' — ' 

#$0D:BEQ  TARGET.  So,  while  CMP  is  sometimes  not  ab- 
solutely necessary,  it  will  never  hurt  to  include  it  prior  to  \    I 
branching.  ' — ' 

Another  important  branch  decision  is  based  on  >  or  < 
situations.  In  this  case,  you  use  BCC  and  BCS  to  test  the  C  !    I 

(carry)  flag.  And  you've  got  to  keep  in  mind  the  order  of  the  ( — ' 

numbers  being  compared.  The  memory  byte  is  compared  to 
the  byte  sitting  in  the  accumulator.  The  structure  is  accu-  j    | 

mulator  value  is  less  than  memory  (BCC  is  triggered  because  ' — ' 
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the  carry  flag  was  cleared).  Or  accumulator  value  is  more  than 
or  equal  to  memory  (BCS  is  triggered  because  the  carry  flag 
was  set).  Here's  an  example.  If  you  want  to  find  out  if  the 
number  in  the  accumulator  is  less  than  $40,  just  CMP 
#$40:BCC  LESSTHAN: 

LDA  #75 

CMP  #$40;  IS  IT  LESS  THAN  $40? 

BCC  LESSTHAN 

One  final  comment  about  the  useful  BCC/BCS  tests 
following  CMP:  It's  easy  to  remember  that  BCC  means  less 
than  and  BCS  means  more  than  or  equal  if  you  notice  that  C  is 
less  than  S  in  the  alphabet. 

The  other  flag  affected  by  CMPs  is  the  N  flag.  Its  uses  are 
limited  since  it  merely  reports  the  status  of  the  seventh  bit; 
BPL  triggers  if  that  bit  is  clear,  BMI  triggers  if  it's  set.  How- 
ever, that  seventh  bit  does  show  whether  the  number  is 
greater  than  (or  equal  to)  or  less  than  128,  and  you  can  apply 
this  information  to  the  ASCII  code  or  to  look  for  BASIC 
keywords  or  to  search  databases  (BPL  and  BMI  are  used  by 
LADS's  database  search  routines  in  the  Array  subprogram). 
Nevertheless,  since  LDA  and  many  other  instructions  affect 
the  N  flag,  you  can  often  directly  BPL  or  BMI  without  any 
need  to  CMP  first. 

Addressing  modes: 


Name 

Format 

Opcode 

Bytes  Used 

Immediate 

CMP  #15 

$C9/201 

2 

Zero  Page 

CMP  15 

$C5/197 

2 

Zero  Page,X 

CMP  15,X 

$D5/213 

2 

Absolute 

CMP  1500 

$CD/205 

3 

Absolute,X 

CMP  1500,X 

$DD/221 

3 

Absolute,Y 

CMP  1500,Y 

$D9/217 

3 

Indirect,X 

CMP  (15,X) 

$C1/193 

2 

Indirect,Y 

CMP  (15),Y 

$Dl/209 

2 

Affected  flags: 

NZC 

CPX 

What  it  does:  Compares  the  byte  in  memory  to  the  byte 
in  the  X  register.  Three  flags  are  affected,  but  the  bytes  in 
memory  and  in  the  X  register  are  undisturbed.  A  CPX  is  ac- 
tually a  subtraction  of  the  byte  in  memory  from  the  byte  in 
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the  X  register.  Therefore,  if  you  LDA  #15:CPX  #15,  the  result 
(of  the  subtraction)  will  be  zero,  and  BEQ  would  be  triggered 
since  the  CPX  would  have  set  the  Z  flag. 

Major  uses:  X  is  generally  used  as  an  index,  a  counter 
within  loops.  Though  the  Y  register  is  often  preferred  as  an  in- 
dex since  it  can  serve  for  the  very  useful  indirect  Y  addressing 
mode  (LDA  (15),Y),  the  X  register  is  nevertheless  pressed  into  .    | 

service  when  more  than  one  index  is  necessary  or  when  Y  is  ( — i 

busy  with  other  tasks. 

In  any  case,  the  flags,  conditions,  and  purposes  of  CPX 
are  quite  similar  to  CMP  (the  equivalent  comparison  instruc- 
tion for  the  accumulator).  For  further  information  on  the  vari- 
ous possible  comparisons  (greater  than,  equal,  less  than,  not 
equal),  see  CMP  above. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Immediate  CPX  #15  $E0/224  2 

Zero  Page  CPX  15  $E4/228  2 

Absolute  CPX  1500  $EC/236  3 

Affected  flags:  N  Z  C 


CPY 

What  it  does:  Compares  the  byte  in  memory  to  the  byte 
in  the  Y  register.  Three  flags  are  affected,  but  the  bytes  in 
memory  and  in  the  Y  register  are  undisturbed.  A  CPX  is  ac- 
tually a  subtraction  of  the  byte  in  memory  from  the  byte  in 
the  Y  register.  Therefore,  if  you  LDA  #15:  CPY  #15,  the  result 
(of  the  subtraction)  will  be  zero,  and  BEQ  would  be  triggered 
since  the  CPY  would  have  set  the  Z  flag. 

Major  uses:  Y  is  the  most  popular  index,  the  most  heavily 
used  counter  within  loops  since  it  can  serve  two  purposes:  It 
permits  the  very  useful  indirect  Y  addressing  mode — LDA  ^    ( 

(15),Y — and  can  simultaneously  maintain  a  count  of  loop  events.  i — i 

See  CMP  above  for  a  detailed  discussion  of  the  various 
branch  comparisons  which  CPY  can  implement.  I    . 
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f-j  Addressing  modes: 


Name 

pi  Immediate 

-   •  Zero  Page 

Absolute 

f*J  Affected  flags:  N  Z  C 


Format 

Opcode 

Bytes  Used 

CPY  #15 

$C0/192 

2 

CPY15 

$C4/196 

2 

CPY  1500 

$CC/204 

3 

DEC 

What  it  does:  Reduces  the  value  of  a  byte  in  memory  by 
1.  The  N  and  Z  flags  are  affected. 

Major  uses:  A  useful  alternative  to  SBC  when  you  are 
reducing  the  value  of  a  memory  address.  DEC  is  simpler  and 
shorter  than  SBC,  and  although  DEC  doesn't  affect  the  C  flag, 
you  can  still  decrement  double-byte  numbers  (see  "Decrement 
Double-Byte  Numbers"  in  Appendix  E). 

The  other  main  use  for  DEC  is  to  control  a  memory  index 
when  the  X  and  Y  registers  are  too  busy  to  provide  this  ser- 
vice. For  example,  you  could  define,  say,  address  $505  as  a 
counter  for  a  loop  structure.  Then  LOOP  STA  $8000:DEC 
$505:BEQ  END:JMP  LOOP.  This  structure  would  continue 
storing  A  into  $8000  until  address  $505  was  decremented  to 
zero.  This  imitates  DEX  or  DEY  and  allows  you  to  set  up  as 
many  nested  loop  structures  (loops  within  loops)  as  you  wish. 

Addressing  modes: 


Name 
Zero  Page 
Zero  Page,X 
Absolute 
Absolute,X 

Affected  flags: 

Format 

DEC  15 
DEC  15,X 
DEC  1500 
DEC  1500,X 

NZ 

Opcode 

$C6/198 
$D6/214 
$CE/206 
$DE/222 

Bytes  Used 

2 
2 
3 

3 

DEX 

What  it  does:  Reduces  the  X  register  by  1. 

Major  uses:  Used  as  a  counter  (an  index)  within  loops. 
Normally,  you  LDX  with  some  number  (the  number  of  times 
you  want  the  loop  executed)  and  then  DEX:BEQ  END  as  a 
way  of  counting  events  and  exiting  the  loop  at  the  right  time. 
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Addressing  modes: 

Name                       Format 
Implied                    DEX 

Affected  flags:  N  Z 

Opcode 

$CA/202 

Bytes  Used 
1 

U 

u 
u 

DEY 

u 

What  it  does:  Reduces  the  Y  register  by  1. 

Major  uses:  Like  DEX,  DEY  is  often  used  as  a  counter  for 
loop  structures.  But  DEY  is  the  more  common  of  the  two  since 
the  Y  register  can  simultaneously  serve  two  purposes  within 
a  loop  by  permitting  the  very  popular  indirect  Y  addressing 
mode.  A  common  way  to  print  a  screen  message  (the  ASCII 
form  of  the  message  is  at  $5000  in  this  example,  and  the  mes- 
sage ends  with  zero):  LDY  #0:LOOP  LDA  $5000,Y:BEQ 
END:STA  SCREEN,Y:INY:JMP  LOOP:END  and  continue  with 
the  program. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Implied  DEY  $88/136  1 

Affected  flags:  N  Z 


EOR 

What  it  does:  Exclusive-ORs  a  byte  in  memory  with  the 
accumulator.  Each  bit  in  memory  is  compared  with  each  bit  in 
the  accumulator,  and  the  bits  are  then  set  (given  a  one)  if  one 
of  the  compared  bits  is  one.  However,  bits  are  cleared  if  both 
are  zero  or  if  both  are  one.  The  bits  in  the  byte  held  in  the 
accumulator  are  the  only  ones  affected  by  this  comparison.  1 [ 

Major  uses:  EOR  doesn't  have  too  many  uses.  Its  main 
value  is  to  toggle  a  bit.  If  a  bit  is  clear  (is  a  zero),  it  will  be  set 

(to  a  one);  if  a  bit  is  set,  it  will  be  cleared.  For  example,  if  you  1 I 

want  to  reverse  the  current  state  of  the  sixth  bit  in  a  given 
byte:  LDA  BYTE:EOR  #$40:STA  BYTE.  This  will  set  bit  6  in 

BYTE  if  it  was  zero  (and  clear  it  if  it  was  one).  This  selective  J j 

bit  toggling  could  be  used  to  "shift"  an  unshifted  ASCII 

character  via  EOR  #$80  (1000000).  Or  if  the  character  were 

shifted,  EOR  #$80  would  make  it  lowercase.  EOR  toggles.  LJ 
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Addressing  modes: 

Name 

Format 

Opcode 

Bytes  Used 

Immediate 

EOR  #15 

$49/73 

2 

Zero  Page 

EOR15 

$45/69 

2 

Zero  Page,X 

EOR  15,X 

$55/85 

2 

Absolute 

EOR  1500 

$4D/77 

3 

Absolute,X 

EOR  1500,X 

$5D/93 

3 

Absolute,Y 

EOR  1500,  Y 

$59/89 

3 

Indirect,X 

EOR  (15,X) 

$41/65 

2 

Indirect,Y 

EOR  (15),  Y 

$51/81 

2 

Affected  flags: 

NZ 

INC 


What  it  does:  Increases  the  value  of  a  byte  in  memory 
by  1. 

Major  uses:  Used  exactly  as  DEC  (see  DEC  above),  except 
it  counts  up  instead  of  down.  For  raising  address  pointers  or 
supplementing  the  X  and  Y  registers  as  loop  indexes. 

Addressing  modes: 


Name 

Zero  Page 
Zero  Page,X 
Absolute 
Absolute,X 

Affected  flags:  N  Z 


Format 

INC  15 
INC  15,X 
INC  1500 
INC  1500,X 


Opcode 

$E6/230 
$F6/246 
$EE/238 
$FE/254 


Bytes  Used 

2 

2 
3 
3 


n 


i   ( 


H 


INX 

What  it  does:  Increases  the  X  register  by  1. 
Major  uses:  Used  exactly  as  DEX  (see  DEX  above),  except 
it  counts  up  instead  of  down.  For  loop  indexing. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Implied  INX  $E8/232  1 

Affected  flags:  N  Z 


n 
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INY 

What  it  does:  Increases  the  Y  register  by  1. 

Major  uses:  Used  exactly  as  DEY  (see  DEY  above),  except 

it  counts  up  instead  of  down.  For  loop  indexing  and  working  |    i 

with  the  indirect  Y  addressing  mode — LDA  (15),Y.  < — ' 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Implied  INY  $C8/200  1 

Affected  flags:  N  Z 


u 


JMP 

What  it  does:  Jumps  to  any  location  in  memory. 

Major  uses:  Branching  long  range.  It  is  the  equivalent  of 
BASIC'S  GOTO  instruction.  The  bytes  in  the  program  counter 
are  replaced  with  the  address  (the  argument)  following  the 
JMP  instruction  and,  therefore,  program  execution  continues 
from  this  new  address. 

Indirect  jumping — JMP  (1500) — is  not  recommended,  al- 
though some  programmers  find  it  useful.  It  allows  you  to  set 
up  a  table  of  jump  targets  and  bounce  off  them  indirectly.  For 
example,  if  you  had  placed  the  numbers  $00  $04  in  addresses 
$88  and  $89,  a  JMP  ($0088)  instruction  would  send  the  pro- 
gram to  whatever  ML  routine  was  located  in  address  $0400. 
Unfortunately,  if  you  should  locate  one  of  your  pointers  on 
the  edge  of  a  page  (for  example,  $00FF  or  $17FF),  this  indirect 
JMP  addressing  mode  reveals  its  great  weakness.  There  is  a 
bug  which  causes  the  jump  to  travel  to  the  wrong  place — JMP 
($00FF)  picks  up  the  first  byte  of  the  pointer  from  $00FF,  but 
the  second  byte  of  the  pointer  will  be  incorrectly  taken  from 
$0000.  With  JMP  ($17FF),  the  second  byte  of  the  pointer 
would  come  from  what's  in  address  $1700. 

Since  there  is  this  bug  and  since  there  are  no  compelling  \    / 

reasons  to  set  up  JMP  tables,  you  might  want  to  forget  you  i — < 

ever  heard  of  indirect  jumping. 

Addressing  modes:  I    I 

Name  Format  Opcode  Bytes  Used 

Absolute  JMP  1500  $4C/76  3  , 

Indirect  JMP  (1500)  $6C/108  3  Li 

Affected  flags:  None 
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n       jsr 

What  it  does:  Jumps  to  a  subroutine  anywhere  in  mem- 
ory. Saves  the  PC  (Program  Counter)  address,  plus  three,  of 
the  JSR  instruction  by  pushing  it  onto  the  stack.  The  next  RTS 
in  the  program  will  then  pull  that  address  off  the  stack  and  re- 
turn to  the  instruction  following  the  JSR. 

Major  uses:  As  the  direct  equivalent  of  BASIC'S  GOSUB 
command,  JSR  is  heavily  used  in  ML  programming  to  send 
control  to  a  subroutine  and  then  (via  RTS)  to  return  and  pick 
up  where  you  left  off.  The  larger  and  more  sophisticated  a 
program  becomes,  the  more  often  JSR  will  be  invoked.  In  LADS, 
whenever  something  is  printed  to  screen  or  printer,  you'll 
often  see  a  chain  of  JSRs  performing  necessary  tasks:  JSR 
PRNTCR:  JSR  PRNTSAJSR  PRNTSPACEJSR  PRNTNUMJSR 
PRNTSPACE.  This  JSR  chain  prints  a  carriage  return,  the  cur- 
rent assembly  address,  a  space,  a  number,  and  another  space. 

Another  thing  you  might  notice  in  LADS  and  other  ML 
programs  is  a  PLA:PLA  pair.  Since  JSR  stuffs  the  correct  return 
address  onto  the  stack  before  leaving  for  a  subroutine,  you 
need  to  do  something  about  that  return  address  if  you  later 
decide  not  to  RTS  back  to  the  position  of  the  JSR  in  the  pro- 
gram. This  might  be  the  case  if  you  usually  want  to  RTS,  but 
in  some  particular  cases,  you  don't.  For  those  cases,  you  can 
take  control  of  program  flow  by  removing  the  return  address 
from  the  stack  (PLA:PLA  will  clean  off  the  two-byte  address) 
and  then  performing  a  direct  JMP  to  wherever  you  want  to  go. 

If  you  JMP  out  of  a  subroutine  without  PLA:PLA,  you 
could  easily  overflow  the  stack  and  crash  the  program. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Absolute  JSR  1500  $20/32  3 


Affected  flags:  None 


LDA 

What  it  does:  Loads  the  accumulator  with  a  byte  from 
memory.  Copy  might  be  a  better  word  than  load,  since  the  byte 
in  memory  is  unaffected  by  the  transfer. 

Major  uses:  The  busiest  place  in  the  computer.  Bytes 
coming  in  from  disk,  tape,  or  keyboard  all  flow  through  the 
accumulator,  as  do  bytes  on  their  way  to  screen  or  peripherals. 
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Also,  because  the  accumulator  differs  in  some  important  ways 
from  the  X  and  Y  registers,  the  accumulator  is  used  by  ML 
programmers  in  a  different  way  from  the  other  registers. 

Since  INY/DEY  and  INX/DEX  make  those  registers  useful 
as  counters  for  loops  (the  accumulator  couldn't  be  conve- 
niently employed  as  an  index;  there  is  no  INA  instruction),  the 
accumulator  is  the  main  temporary  storage  register  for  bytes  • 
during  their  manipulation  in  an  ML  program.  ML  program- 
ming, in  fact,  can  be  defined  as  essentially  the  rapid,  or- 
ganized maneuvering  of  single  bytes  in  memory.  And  it  is  the 
accumulator  where  these  bytes  often  briefly  rest  before  being 
sent  elsewhere. 

Addressing  modes: 


Name 

Format 

Opcode 

Bytes  Used 

Immediate 

LDA  #15 

$A9/169 

2 

Zero  Page 

LDA15 

$A5/165 

2 

Zero  Page,X 

LDA  15,X 

$B5/181 

2 

Absolute 

LDA  1500 

$AD/173 

3 

Absolute,X 

LDA  1500,X 

$BD/189 

3 

Absolute,Y 

LDA  1500,Y 

$B9/185 

3 

Indirect,X 

LDA  (15,X) 

$A1/161 

2 

Indirect,Y 

LDA  (15),Y 

$B1/177 

2 

Affected  flags: 

NZ 

u 

u 

Li 


LDX 

What  it  does:  Loads  the  X  register  with  a  byte  from 
memory. 

Major  uses:  The  X  register  can  perform  many  of  the  tasks 
that  the  accumulator  performs,  but  it  is  generally  used  as  an 
index  for  loops.  In  preparation  for  its  role  as  an  index,  LDX 
puts  a  value  into  the  register. 

Addressing  modes: 


Name 

Immediate 
Zero  Page 
Zero  Page,Y 
Absolute 
Absolute,Y 

Affected  flags:  N  Z 


Format 

LDX  #15 
LDX  15 
LDX  15,Y 
LDX  1500 
LDX  1500,Y 


Opcode 

$A2/162 
$A6/166 
$B6/182 
$AE/174 
$BE/190 


Bytes  Used 

2 
2 
2 
3 
3 


U 
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LDY 

What  it  does:  Loads  the  Y  register  with  a  byte  from 
memory. 

Major  uses:  The  Y  register  can  perform  many  of  the  tasks 
that  the  accumulator  performs,  but  it  is  generally  used  as  an 
index  for  loops.  In  preparation  for  its  role  as  an  index,  LDY 
puts  a  value  into  the  register. 

Addressing  modes: 


Name 

Immediate 
Zero  Page 
Zero  Page,X 
Absolute 
Absolute,X 

Affected  flags:  N  Z 


Format 

LDY  #15 
LDY  15 
LDY  15,X 
LDY  1500 
LDY  1500,X 


Opcode 

$A0/160 

$A4/164 

$B4/180 

$AC/172 

$BC/188 


Bytes  Used 

2 

2 
2 
3 
3 


LSR 

What  it  does:  Shifts  the  bits  in  the  accumulator  or  in  a 
byte  in  memory  to  the  right  by  one  bit.  A  zero  is  stuffed  into 
bit  7,  and  bit  0  is  put  into  the  carry  flag. 


0 


VTvTvTvTvT*'TvT* 


Bit     Bit     Bit     Bit     Bit     Bit     Bit     Bit 
7       6       5       4       3       2       10 


Carry 
Flag 


Major  uses:  To  divide  a  byte  by  2.  In  combination  with 
the  ROR  instruction,  LSR  can  divide  a  two-byte  or  larger  num- 
ber (see  Appendix  E). 

LSR:LSR:LSR:LSR  will  put  the  high  four  bits  (the  high 
nybble)  into  the  low  nybble  (with  the  high  nybble  replaced  by 
the  zeros  being  stuffed  into  the  seventh  bit  and  then  shifted  to 
the  right). 
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Name                      Format 

Accumulator            LSR 
Zero  Page                LSR  15 
Zero  Page,X             LSR  15,X 
Absolute                  LSR  1500 
Absolute,X               LSR  1500,X 

Opcode 

$4A/74 
$46/70 
$56/86 
$4E/78 
$5E/94 

Bytes  Used 

2 
2 
2 
3 

3 

Li 

Affected  flags:  N  Z  C 

NOP 

What  it  does:  Nothing;  NO  oPeration. 

Major  uses:  Debugging.  When  setting  breakpoints  with 
BRK,  you  will  often  discover  that  a  breakpoint,  when  exam- 
ined, passes  the  test.  That  is,  there  is  nothing  wrong  at  that 
place  in  the  program.  So,  to  allow  the  program  to  execute  to 
the  next  breakpoint,  you  cover  the  BRK  with  a  NOP.  Then, 
when  you  run  the  program,  the  computer  will  slide  over  the 
NOP  with  no  effect  on  the  program.  Three  NOPs  could  cover 
a  JSR  XXXX,  and  you  could  see  the  effect  on  the  program 
when  that  particular  JSR  is  eliminated. 

Addressing  modes: 

Opcode  Bytes  Used 

$EA/234  1 


Name 

Format 

Implied 

NOP 

Affected 

flags: 

None 

ORA 

What  it  does:  Logically  ORs  a  byte  in  memory  with  the 
byte  in  the  accumulator.  The  result  is  in  the  accumulator.  An 
OR  results  in  a  one  if  either  the  bit  in  memory  or  the  bit  in 
the  accumulator  is  one. 

Major  uses:  Like  an  AND  mask  which  turns  bits  off,  ORA 
masks  can  be  used  to  turn  bits  on.  For  example,  if  you  wanted 
to  "shift"  an  ASCII  character  by  setting  the  seventh  bit,  you 
could  LDA  CHARACTER:ORA  #$80.  The  number  $80  in  bi- 
nary is  10000000,  so  all  the  bits  in  CHARACTER  which  are 
ORed  with  zeros  here  will  be  left  unchanged.  (If  a  bit  in  t    , 

CHARACTER  is  a  one,  it  stays  a  one.  If  it  is  a  zero,  it  stays  L~> 

zero.)  But  the  one  in  the  seventh  bit  of  $80  will  cause  a  zero 
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in  the  CHARACTER  to  turn  into 

a  one.  (If  CHARACTER  al- 

ready  has  a  one  in  its  seventh  bit,  it  will  remain  a  one.) 

n 

Addressing  modes: 

Name 

Format 

Opcode 

Bytes  Used 

Immediate 

ORA#15 

$09/9 

2 

1 1 

Zero  Page 

ORA15 

$05/5 

2 

> i 

Zero  Page,X 

ORA  15,X 

$15/21 

2 

Absolute 

ORA  1500 

$0D/13 

3 

Absolute,X 

ORA  1500,X 

$lD/29 

3 

Absolute,Y 

ORA  1500,Y 

$19/25 

3 

Indirect,X 

ORA  (15,X) 

$01/1 

2 

Indirect,Y 

ORA  (15),Y 

$11/17 

2 

Affected  flags: 

NZ 

n 


PHA 

What  it  does:  Pushes  the  accumulator  onto  the  stack. 

Major  uses:  To  temporarily  (very  temporarily)  save  the 
byte  in  the  accumulator.  If  you  are  within  a  particular  sub- 
routine and  you  need  to  save  a  value  for  a  brief  time,  you  can 
PHA  it.  But  beware  that  you  must  PLA  it  back  into  the  accu- 
mulator before  any  RTS  so  that  it  won't  misdirect  the  computer 
to  the  wrong  RTS  address.  All  RTS  addresses  are  saved  on  the 
stack.  Probably  a  safer  way  to  temporarily  save  a  value  (a 
number)  would  be  to  STA  TEMP  or  put  it  in  some  other  tem- 
porary variable  that  you've  set  aside  to  hold  things.  Also,  the 
values  of  A,  X,  and  Y  need  to  be  temporarily  saved,  and  the 
programmer  will  combine  TYA  and  TXA  with  several  PHAs  to 
stuff  all  three  registers  onto  the  stack.  But,  again,  matching 
PLAs  must  restore  the  stack  as  soon  as  possible  and  certainly 
prior  to  any  RTS. 

Addressing  modes: 

Name  Format  Opcode 

Implied  PHA  $48/72 

Affected  flags:  None 


Bytes  Used 

1 


n 
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PHP  jj 

What  it  does:  Pushes  the  "processor  status"  onto  the  top 
of  the  stack.  This  byte  is  the  status  register,  the  byte  which 
holds  all  the  flags:  NZCIDV.  [_] 

Major  uses:  To  temporarily,  very  temporarily,  save  the 
state  of  the  flags.  If  you  need  to  preserve  all  current  conditions 
for  a  minute  (see  description  of  PHA  above),  you  may  also  j    [ 

want  to  preserve  the  status  register  as  well.  You  must,  how- 
ever,  restore  the  status  register  byte  and  clean  up  the  stack  by 
using  a  PLP  before  the  next  RTS. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Implied  PHP  $08/8  1 

Affected  flags:  None 


PLA 

What  it  does:  Pulls  the  top  byte  off  the  stack  and  puts  it 
into  the  accumulator. 

Major  uses:  To  restore  a  number  which  was  temporarily 
stored  on  top  of  the  stack  (with  the  PHA  instruction).  It  is  the 
opposite  action  of  PHA  (see  above).  Note  that  PLA  does  affect 
the  N  and  Z  flags.  Each  PHA  must  be  matched  by  a  corre- 
sponding PLA  if  the  stack  is  to  correctly  maintain  RTS  ad- 
dresses, which  is  the  main  purpose  of  the  stack. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Implied  PLA  $68/104  1 

Affected  flags:  N  Z  U 


PLP 

What  it  does:  Pulls  the  top  byte  off  the  stack  and  puts  it 
into  the  status  register  (where  the  flags  are).  PLP  is  a  mne- 
monic for  PuLl  Processor  status. 

Major  uses:  To  restore  the  condition  of  the  flags  after  the 
status  register  has  been  temporarily  stored  on  top  of  the  stack 
(with  the  PHP  instruction).  It  is  the  opposite  action  of  PHP 
(see  above).  PLP,  of  course,  affects  all  the  flags.  Any  PHP 

236 


U 


u 


n 


Appendix  A 


!    1 


must  be  matched  by  a  corresponding  PLP  if  the  stack  is  to  cor- 
rectly maintain  RTS  addresses,  which  is  the  main  purpose  of 
the  stack. 


Addressing  modes: 

Name  Format 

Implied  PLP 

Affected  flags:  All 


Opcode 

$28/40 


Bytes  Used 
1 


ROL 

What  it  does:  Rotates  the  bits  in  the  accumulator  or  in  a 
byte  in  memory  to  the  left  by  one  bit.  A  rotate  left  (as  op- 
posed to  an  ASL,  Arithmetic  Shift  Left)  moves  bit  7  to  the 
carry,  moves  the  carry  into  bit  0,  and  every  other  bit  moves  one 
position  to  its  left.  (ASL  operates  quite  similarly,  except  it  al- 
ways puts  a  zero  into  bit  0.) 


/P-/T-/iVTvTy'iVT- 


Bit     Bit     Bit     Bit     Bit     Bit     Bit     Bit 
7       6       5       4       3       2        10 


Major  uses:  To  multiply  a  byte  by  2.  ROL  can  be  used 
with  ASL  to  multiply  multiple-byte  numbers  since  ROL  pulls 
any  carry  into  bit  0.  If  an  ASL  resulted  in  a  carry,  it  would  be 
thus  taken  into  account  in  the  next  higher  byte  in  a  multiple- 
byte  number.  (See  Appendix  E.) 

Notice  how  the  act  of  moving  columns  of  binary  numbers 
to  the  left  has  the  effect  of  multiplying  by  2: 

0010  The  number  2  in  binary 
0100  The  number  4 

This  same  effect  can  be  observed  with  decimal  numbers, 
except  the  columns  represent  powers  of  10: 

0010  The  number  10  in  decimal 
0100  The  number  100 
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Addressing  modes: 

Li 

Name 

Accumulator 
Zero  Page 
Zero  Page,X 
Absolute 
Absolute,X 

Format 

ROL 
ROL  15 
ROL  15,X 
ROL  1500 
ROL  1500,X 

Opcode 

$2A/42 
$26/38 
$36/54 
$2E/46 
$3E/62 

Bytes  Used 

1 

2 
2 
3 
3 

u 

u 

Affected  flags:  N  Z  C 

ROR 

What  it  does:  Rotates  the  bits  in  the  accumulator  or  in  a 
byte  in  memory  to  the  right  by  one  bit.  A  rotate  right  (as  op- 
posed to  an  LSR,  Logical  Shift  Right)  moves  bit  0  into  the 
carry,  moves  the  carry  into  bit  7,  and  every  other  bit  moves  one 
position  to  its  right.  (LSR  operates  quite  similarly,  except  it  al- 
ways puts  a  zero  into  bit  7.) 


'9v?vTvT* '?*  *?v?* 


Bit     Bit     Bit     Bit     Bit     Bit     Bit     Bit 
7       6       5       4       3       2       10 


Major  uses:  To  divide  a  byte  by  2.  ROR  can  be  used  with 
LSR  to  divide  multiple-byte  numbers  since  ROR  puts  any 
carry  into  bit  7.  If  an  LSR  resulted  in  a  carry,  it  would  be  thus 
taken  into  account  in  the  next  lower  byte  in  a  multiple-byte 
number.  (See  Appendix  E.)  \    { 

Notice  how  the  act  of  moving  columns  of  binary  numbers  ^ 

to  the  right  has  the  effect  of  dividing  by  2: 

1000  The  number  8  in  binary  \-   \ 

0100  The  number  4  '     ' 

This  same  effect  can  be  observed  with  decimal  numbers,  . 

except  the  columns  represent  powers  of  10:  i_J 

1000  The  number  1000  in  decimal 

0100  The  number  100  ,     , 
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Addressing  modes: 

Name 

Accumulator 
Zero  Page 
Zero  Page,X 
Absolute 
Absolute,X 

Affected  flags:  N  Z  C 


Format 
ROR 
ROR15 
ROR  15,X 
ROR  1500 
ROR  1500,X 


Opcode 

$6A/106 
$66/102 
$76/118 
$6E/110 
$7E/126 


Bytes  Used 
1 

2 
2 
3 
3 


RTI 

What  it  does:  Returns  from  an  interrupt. 

Major  uses:  None.  You  might  want  to  add  your  own 
routines  to  your  machine's  normal  interrupt  routines  (see  SEI 
below),  but  you  won't  be  generating  actual  interrupts  of  your 
own.  Consequently,  you  cannot  ReTurn  from  Interrupts  you 
never  create. 


Addressing  modes: 

Name  Format  Opcode 

Implied  RTI  $40/64 

Affected  flags:  All  (status  register  is  retrieved  from  the  stack) 


Bytes  Used 

1 


RTS 


f"-< 


n 

n 
n 


What  it  does:  Returns  from  a  subroutine  jump  (caused  by 
JSR). 

Major  uses:  Automatically  picks  off  the  two  top  bytes  on 
the  stack  and  places  them  into  the  program  counter.  This  re- 
verses the  actions  taken  by  JSR  (which  put  the  program 
counter  bytes  onto  the  stack  just  before  leaving  for  a  sub- 
routine). When  RTS  puts  the  return  bytes  into  the  program 
counter,  the  next  event  in  the  computer's  world  will  be  the 
instruction  following  the  JSR  which  stuffed  the  return  address 
onto  the  stack  in  the  first  place. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Implied  RTS  $60/96  1 

Affected  flags:  None 
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SBC 

What  it  does:  Subtracts  a  byte  in  memory  from  the  byte 
in  the  accumulator,  and  "borrows"  if  necessary.  If  a  "borrow" 
takes  place,  the  carry  flag  is  cleared  (set  to  zero).  Thus,  you  al- 
ways SEC  (set  the  carry  flag)  before  an  SBC  operation  so  that 
you  can  tell  if  you  need  a  "borrow."  In  other  words,  when  an 
SBC  operation  clears  the  carry  flag,  it  means  that  the  byte  in 
memory  was  larger  than  the  byte  in  the  accumulator.  And 
since  memory  is  subtracted  from  the  accumulator  in  an  SBC 
operation,  if  memory  is  the  larger  number,  we  must  "borrow." 

Major  uses:  Subtracts  one  number  from  another. 

Addressing  modes: 


Name 

Format 

Opcode 

Bytes  Used 

Immediate 

SBC  #15 

$E9/233 

2 

Zero  Page 

SBC  15 

$E5/229 

2 

Zero  Page,X 

SBC  15,X 

$F5/245 

2 

Absolute 

SBC  1500 

$ED/237 

3 

Absolute,X 

SBC  1500,X 

$FD/253 

3 

Absolute,Y 

SBC  1500,Y 

$F9/249 

3 

Indirect,X 

SBC  (15,X) 

$El/225 

2 

Indirect,Y 

SBC  (15),Y 

$F1/241 

2 

Affected  flags: 

NZC  V 

u 

u 
u 


u 


SEC 

What  it  does:  Sets  the  carry  (C)  flag  (in  the  processor  sta- 
tus register  byte). 

Major  uses:  This  instruction  is  always  used  before  any 
SBC  operation  to  show  if  the  result  of  the  subtraction  was 
negative  (if  the  accumulator  contained  a  smaller  number  than 
the  byte  in  memory  being  subtracted  from  it).  See  SBC  above. 

Addressing  modes: 


Name  Format 

Implied  SEC 

Affected  flags:  C 


Opcode 

$38/56 


Bytes  Used 

1 


u 


/ 


SED 

What  it  does:  Sets  the  decimal  (D)  flag  (in  the  processor 
status  register  byte). 

240 


U 


n 


Appendix  A 


f— j  Major  uses:  Setting  this  flag  puts  the  8502  into  decimal 

arithmetic  mode.  This  mode  can  be  easier  to  use  when  you  are 
inputting  or  outputting  decimal  numbers  (from  the  user  of  a 

f*"1  program  or  to  the  screen).  Simple  addition  and  subtraction  can 

be  performed  in  decimal  mode,  but  most  programmers  ignore 
this  feature  since  more  complicated  math  requires  that  you  re- 

|— I  main  in  the  normal  binary  state  of  the  8502. 

Note:  Commodore  computers  automatically  clear  this 
mode  when  powered  on  or  when  entering  ML  via  SYS.  How- 
ever, Apple  and  Atari  computers  can  enter  ML  in  an  in- 
determinate state.  Since  there  is  a  possibility  that  the  D  flag 
might  be  set  (causing  havoc)  on  entry  to  an  ML  routine,  it  is 
sometimes  suggested  that  Apple  and  Atari  owners  use  the 
CLD  instruction  at  the  start  of  any  ML  program  they  write. 
Fortunately  Commodore  users  do  not  need  to  worry  about 
this,  but  all  ML  programmers  must  CLD  following  any  delib- 
erate use  of  the  decimal  mode  (see  SED). 


Addressing  modes: 

Name 

Implied 

Affected  flags:  D 


Name  Format  Opcode  Bytes  Used 

Implied  SED  $F8/248  1 


SEI 

What  it  does:  Sets  the  interrupt  disable  flag  (the  I  flag)  in 
the  processor  status  byte.  When  this  flag  is  up,  the  8502  will 
not  acknowledge  or  act  upon  interrupt  attempts  (except  a  few 
nonmaskable  interrupts  which  can  take  control  in  spite  of  this 
flag,  like  a  reset  of  the  entire  computer).  The  operating  sys- 

r~!  terns  of  most  computers  will  regularly  interrupt  the  activities 

of  the  chip  for  necessary,  high-priority  tasks  such  as  updating 
an  internal  clock,  displaying  things  on  the  TV,  receiving  sig- 

["""}  nals  from  the  keyboard,  and  so  forth.  These  interruptions  of 

whatever  the  chip  is  doing  normally  occur  60  times  every  sec- 
ond. To  find  out  what  housekeeping  routines  your  computer 

{~"j  interrupts  the  chip  to  accomplish,  look  at  the  pointer  in 

$FFFE/FFFF.  It  gives  the  starting  address  of  the  maskable 
interrupt  routines. 

|~"1  Major  uses:  You  can  alter  a  RAM  pointer  so  that  it  sends 

these  interrupts  to  your  own  ML  routine,  and  your  routine  then 
would  conclude  by  pointing  to  the  normal  interrupt  routines. 


n 
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In  this  way,  you  can  add  something  you  want  (a  click  sound 
for  each  keystroke?  the  time  of  day  on  the  screen?)  to  the  nor- 
mal actions  of  your  operating  system.  The  advantage  of  this 
method  over  normal  SYSing  is  that  your  interrupt-driven  rou- 
tine is  essentially  transparent  to  whatever  else  you  are  doing 
(in  whatever  language).  Your  customization  appears  to  have 
become  part  of  the  computer's  ordinary  habits. 

However,  if  you  try  to  alter  the  RAM  pointer  while  the 
other  interrupts  are  active,  you  will  point  away  from  the  nor- 
mal housekeeping  routines  in  ROM,  crashing  the  computer. 
This  is  where  SEI  comes  in.  You  disable  the  interrupts  while 
you  LDA  STA  LDA  STA  the  new  pointer.  Then  CLI  turns  the 
interrupt  back  on  and  nothing  is  disturbed. 

Interrupt  processing  is  a  whole  subcategory  of  ML 
programming  and  has  been  widely  discussed  in  magazine  arti- 
cles. Look  there  if  you  need  more  detail. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Implied  SEI  $78/120  1 

Affected  flags:  I 


U 
U 


u 


u 
u 


STA 

What  it  does:  Stores  the  byte  in  the  accumulator  into 
memory. 

Major  uses:  Can  serve  many  purposes  and  is  among  the 
most  used  instructions.  Many  other  instructions  leave  their  re- 
sults in  the  accumulator  (ADC/SBC  and  logical  operations  like 
ORA),  after  which  they  are  stored  in  memory  with  STA. 


Addressing  rr 

todes: 

W 

Name 

Format 

Opcode 

Bytes  Used 

Zero  Page 

STA  15 

$85/133 

2 

u 

Zero  Page,X 

STA  15,X 

$95/149 

2 

Absolute 

STA  1500 

$8D/141 

3 

Absolute,X 

STA  1500,X 

$9D/157 

3 

u 

Absolute,Y 

STA  1500,Y 

$99/153 

3 

Indirect,X 

STA  (15,X) 

$81/129 

2 

Indirect,Y 

STA  (15),Y 

$91/145 

2 

1      i 

Affected  flags: 

None 

u 
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H 

STX 

What  it  does:  Stores  the  byte  in  the  X 

register  into 

H 

memory. 

Major  uses:  Copies  the  byte  in  X  into 

a  byte  in  memory. 

Addressing  modes: 

n 

Name                       Format                 Opcode 

Zero  Page                 STX  15                 $86/134 
Zero  Page,Y             STX  15,Y             $96/150 
Absolute                  STX  1500             $8E/142 

Affected  flags:  None 

Bytes  Used 

2 
2 
3 

STY 

What  it  does:  Stores  the  byte  in  the  Y  register  into 
memory. 

Major  uses:  Copies  the  byte  in  Y  into  a  byte  in  memory. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Zero  Page  STY  15  $84/132  2 

Zero  Page,X  STY  15,X  $94/148  2 

Absolute  STY  1500  $8C/140  3 

Affected  flags:  None 


H 
H 

n 

H 

n 


TAX 

What  it  does:  Transfers  the  byte  in  the  accumulator  to  the 
X  register. 

Major  uses:  Sometimes  you  can  copy  the  byte  in  the 
accumulator  into  the  X  register  as  a  way  of  briefly  storing  the 
byte  until  it's  needed  again  by  the  accumulator.  If  X  is  cur- 
rently unused,  TAX  is  a  convenient  alternative  to  PHA  (an- 
other temporary  storage  method). 

However,  since  X  is  often  employed  as  a  loop  counter, 
TAX  is  a  relatively  rarely  used  instruction. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Implied  TAX  $AA/170  1 

Affected  flags:  N  Z 
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TAY 

What  it  does:  Transfers  the  byte  in  the  accumulator  to  the 
Y  register. 

Major  uses:  Sometimes  you  can  copy  the  byte  in  the  1    I 

accumulator  into  the  Y  register  as  a  way  of  briefly  storing  the 
byte  until  it's  needed  again  by  the  accumulator.  If  Y  is  cur- 
rently unused,  TAY  is  a  convenient  alternative  to  PHA  (an-  j    i 
other  temporary  storage  method). 

However,  since  Y  is  quite  often  employed  as  a  loop 
counter,  TAY  is  a  relatively  rarely  used  instruction. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Implied  TAY  $A8/168  1 

Affected  flags:  N  Z 


TSX 

What  it  does:  Transfers  the  stack  pointer  to  the  X  register. 

Major  uses:  The  stack  pointer  is  a  byte  in  the  8502  chip 
which  points  to  where  a  new  value  (number)  can  be  added  to 
the  stack.  The  stack  pointer  would  be  "raised"  by  two,  for  ex- 
ample, when  you  JSR  and  the  two  bytes  of  the  program 
counter  are  pushed  onto  the  stack.  The  next  available  space  on 
the  stack  thus  becomes  two  higher  than  it  was  previously.  By 
contrast,  an  RTS  will  pull  a  two-byte  return  address  off  the 
stack,  freeing  up  some  space,  and  the  stack  pointer  would 
then  be  "lowered"  by  two. 

The  stack  pointer  is  always  added  to  $0100  since  the  stack 
is  located  between  addresses  $0100  and  $01FF. 


Addressing  modes:  I — I 

Name  Format  Opcode  Bytes  Used 

Implied  TSX  $BA/186  1  j     | 

Affected  flags:  N  Z 

U 
U 
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J-]  TXA 

What  it  does:  Transfers  the  byte  in  the  X  register  to  the 

accumulator. 
j     i  Major  uses:  There  are  times,  after  X  has  been  used  as  a 

counter,  when  you'll  want  to  compute  something  using  the 

value  of  the  counter.  And  you'll  therefore  need  to  transfer  the 
i"""]  byte  in  X  to  the  accumulator.  For  example,  if  you  search  the 

screen  for  character  $75: 

CHARACTER  =  $75:SCREEN  =  $0400 

LDX#0 

LOOP  LDA  SCREEN,X:CMP  #CHARACTER:BEQ  MORE:INX 

BEQ  NOTFOUND 

;  this  prevents  an  endless  loop 
MORE  TXA  ;  you  now  know  the  character's  location 

NOTFOUND  BRK 

In  this  example,  we  want  to  perform  some  action  based 
on  the  location  of  the  character.  Perhaps  we  want  to  remem- 
ber the  location  in  a  variable  for  later  reference.  This  will  re- 
quire that  we  transfer  the  value  of  X  to  the  accumulator  so 
that  it  can  be  added  to  the  SCREEN  start  address. 


Addressing  modes: 

Name  1 

Implied  1 

Affected  flags:  N  Z 


Name  Format  Opcode  Bytes  Used 

Implied  TXA  $8A/138  1 


TXS 

What  it  does:  Transfers  the  byte  in  X  register  into  the 
stack  pointer. 

Major  uses:  Alters  where,  in  the  stack,  the  current  "here's 
storage  space"  is  pointed  to.  There  are  no  common  uses  for 
this  instruction. 

Addressing  modes: 

Name  Format  Opcode  Bytes  Used 

Implied  TXS  $9A/154  1 

Affected  flags:  None 
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What  it  does:  Transfers  the  byte  in  the  Y  register  to  the 
accumulator. 

Major  uses:  See  TXA. 

U 

i     i 

i     i 

Addressing  modes: 

Name                      Format                Opcode             Bytes  Used 

Implied                    TYA                     $98/152             1 

LJ 

Affected  flags:  N  Z 

I 


u 
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How  to  Use  LADS 


This  appendix  represents  a  step-by-step  explanation  of  how  to 
r^)  assemble  machine  language  programs  using  the  LADS  assem- 

!     (  bier.  As  you  familiarize  yourself  with  its  features  and  practice 

using  it,  you  will  perhaps  discover  things  about  the  assembler 
which  you'd  want  to  modify  to  suit  your  own  programming 
style.  For  example,  if  you  find  that  you  would  prefer  to  re- 
word the  error  messages,  simply  change  them  in  the  Tables 
subprogram  and  run  LADS  through  itself  to  produce  a  new- 
generation  LADS.  For  a  discussion  on  creating  custom  versions 
of  LADS,  see  the  end  of  this  appendix. 

Here,  however,  is  a  description  of  the  features  which  are 
built  into  LADS. 

General  Instructions  for  Using  LADS 

LADS  assembles  from  source  files.  They  are  particularly  easy 
and  convenient  to  create:  Just  turn  on  your  computer  and  pre- 
tend you're  writing  a  BASIC  program.  LADS  works  with 
source  files  created  exactly  the  way  you  would  write  a  BASIC 
program.  You  use  line  numbers,  you  can  use  colons,  you  can 
insert  new  line  numbers  or  delete.  The  only  difference  is  that 
you're  writing  ML,  so  you  use  ML  commands  rather  than 
BASIC  commands.  Here's  an  example  you  can  type  in  and  try. 
Turn  on  your  128  (or  press  the  RESET  button)  and  type  this  in: 

10  *=  2816 

15  .S 
_  16 .0 

(I  20  LDA  #66:LDY  #65 

30  JSR  $FFD2 

40  TYA:JSR  $FFD2 

1    |  As  you  can  see,  it's  quite  similar  to  writing  a  BASIC  pro- 

gram. You  use  line  numbers,  colons,  and  whatever  programmer's 
__  aids  (such  as  automatic  line  numbering)  that  you  ordinarily 

!    !  use  to  write  BASIC  itself.  But  notice  that  if  you  use  colons  you 

should  keep  the  instructions  tight  against  the  colons.  (LDA 
.  #22  :  LDY  #0  would  confuse  LADS.  Spaces  following  a  colon 

(|  won't  cause  any  problems,  but  it's  best  to.  make  a  habit  of 

leaving  no  spaces  around  colons.) 
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Now  you're  ready  to  assemble.  Type  BLOAD  "LADS  and  I     I 

press  RETURN.  Then  type  SYS  10000  to  activate  LADS.  It  will  L-i 

assemble  your  program,  storing  the  resulting  ML  object  code 
(the  runnable  ML  program)  starting  at  address  2816,  and  then  J    | 

return  you  to  BASIC  mode  with  the  familiar  READY.  If  you  ' — ' 

are  using  a  40-column  screen,  it  will  temporarily  go  blank  dur- 
ing the  actual  assembly  because  LADS  switches  to  2  mega-  j     j 
hertz  for  extra  speed.  This  won't  affect  anything,  but  you'll  — ' 
not  see  things  onscreen  during  an  assembly. 

This  example  program  is  supposed  to  print  the  characters 
BA  on  your  screen.  To  test  it,  enter  SYS  2816.  To  change 
things,  just  LIST  your  source  code  and,  perhaps,  change  the 
character  being  printed: 

20  LDA  #66:LDY  #$43;    $43  IS  HEX  FOR  67,  THE  ASCII  CODE 

FOR  "C" 

and  hit  RETURN,  just  as  you  would  to  adjust  a  BASIC  pro- 
gram line.  Now  we've  asked  to  have  the  letters  BC  printed  on 
the  screen.  Again,  activate  LADS  assembly  by  typing  SYS 
10000,  and  then  test  the  results  by  SYS  2816.  It's  as  simple  as 
that. 

But  LADS  has  many  other  features  you'll  find  useful  as 
you  program.  For  example,  if  you've  typed  in  the  "Loader" 
program  (Appendix  F)  or  bought  LADS  on  disk  and  have  a 
1571  disk  drive,  LADS  will  automatically  boot  into  the  128 
when  you  power  up  or  reset.  It  will  also  redefine  the  Fl,  F2, 
F3,  and  F5  keys  to  run  or  reload  LADS  at  the  press  of  a  key,  to 
SYS  2816  ($B00,  the  start  of  many  of  the  examples  in  this 
book),  and  to  invoke  AUTO  10  line  numbering. 

The  Fl  key  will  SYS  10000  and  should  be  used  when 
you're  using  LADS  as  we  did  in  the  example  above.  Use  F3  to 

BLOAD  in  a  fresh  copy  of  LADS  if  it  should  get  corrupted  and  j I 

fail  to  respond.  Users  of  the  1571  disk  drive  might  want  to 
change  the  two  BLOADs  to  BOOTs  in  the  Loader  for  greater 
convenience;  1541  users  should  leave  it  as  BLOAD.  j j 

Few  Rules 

There  are  very  few  absolute  rules  when  using  LADS,  but  one  !     ' 

is  that  you  must  provide  the  starting  address,  the  address  where  '~~ 

you  want  the  ML  program  to  begin  in  the  computer's  memory. 

You  signify  this  with  the  *=  symbol,  which  means  "Program  j 

Counter  equals."  LADS  expects  to  find  this  *=  symbol  as  the 

first  thing  in  your  source  code.  When  LADS  sees  *=,  it  sets 
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f~~ 1  the  program  counter  to  the  number  following  the  equal  sign. 

Remember  also  that  there  must  be  a  space  between  the  =  and 
the  starting  address:  *=  2816,  not  *  =  2816. 

r~|  Also  notice  that  you  can  use  either  decimal  or  hexadeci- 

mal numbers  interchangeably  in  LADS.  Line  20  is  hex  in  the 
example  above  for  the  number  #$43,  but  the  66  is  decimal.  It's 

f""j  up  to  you  which  kind  of  numbers  you  want  to  use  at  any 

given  time. 

Features 

There  are  a  number  of  pseudo-ops  available  in  LADS.  Pseudo- 
ops  are  direct  instructions  to  the  assembler  which  make  things 
easier  for  the  programmer.  The  .S  in  line  15  in  the  example 
above  is  such  an  instruction.  It  tells  LADS  to  print  the  results 
of  an  assembly  to  the  screen.  The  .O  causes  LADS  to  send  the 
results  of  the  assembly,  the  object  code,  to  RAM  memory. 

If  you  add  line  17  to  our  test  program,  you  will  cause  the 
listing  to  be  in  decimal  instead  of  hex: 

10  *=  2816 

15  .S 

16  .O 

17  .NH 

The  pseudo-op  .NH  means  no  hex,  and  causes  the  listing 
to  change  from  hex  to  decimal. 

You  can  add  REM-like  comments  by  using  a  semicolon. 
And  you  can  turn  the  screen  listing  off  with  .NS,  anytime. 
Turn  it  on  or  off  as  much  as  you  want.  This  can  be  an  es- 
pecially useful  switch  if  you  don't  need  to  see  an  entire  listing, 
but  just  want  to  see  how  a  small  section  or  sections  of  your 
program  are  assembling.  Also,  using  .S  will  slow  up  the 
)     i  assembly  process.  The  .S  and  .NS  screen  listings  are  most 

helpful  as  a  kind  of  disassembly  on  the  fly: 

10  *=  2816 

15  .S 

16  .O 

17  .NH 

20  LDA  #66:LDY  #65 
25  .NS 

30  JSR  $FFD2 
40  TYA:JSR  $FFD2 

For  more  complete  listings  and  more  extensive  debugging, 
you  would  want  to  activate  printer  listings  so  you  can  more 
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easily  study  the  flow  of  things  and  make  notes  or  corrections.  J    { 

You  turn  on  printer  listings  with  .P  and  turn  them  off  with  ' — ' 

.NP.  When  you  use  .P,  it  automatically  turns  on  .S,  so  you'll 
see  screen  listings  even  if  you  didn't  include  .S.  1    j 

Because  source  code  comments  would  clutter  up  a  screen  ' — > 

listing,  particularly  a  40-column  screen,  comments  are  sup- 
pressed when  you  use  .S.  However,  comments  are  reproduced  i    [ 
when  you  use  .P  for  printer  listings.  Also,  if  you  are  using  a                ' — ' 
Cardco  interface  with  a  1541  disk  drive,  the  .P  printout  might 
stall.  Should  this  happen,  turn  off  the  disk  drive  and  the  print- 
out will  proceed. 

To  have  the  ML  stored  into  memory  during  assembly,  use 
.O;  to  switch  off  these  POKEs  to  memory,  use  .NO. 

The  pseudo-ops  which  turn  the  printer  on  and  off;  direct 
object  code  to  disk,  screen,  and  RAM;  or  switch  between  hex 
and  decimal  printout  can  be  switched  on  and  off  within  your 
source  code  wherever  convenient.  For  example,  you  can  turn 
on  your  printer  anywhere  within  the  program  by  inserting  .P 
and  turn  it  off  anywhere  with  .NP.  Among  other  things,  this 
would  allow  you  to  specify  that  only  a  particular  section  of  a 
large  program  be  printed  out.  This  can  come  in  very  handy  if 
you're  working  on  a  long  program  where  there  would  be  a 
significant  wait  if  you  had  to  print  out  the  whole  thing. 

Always  put  pseudo-ops  on  a  line  by  themselves.  Any  other 
programming  code  can  be  put  on  a  line  in  any  fashion  (di- 
vided by  colons:  LDA  15:STA  27:INY),  but  pseudo-ops  should 
be  the  only  things  on  their  lines.  (The  .BYTE  pseudo-op, 
described  below,  is  an  exception — it  can  be  on  a  multiple- 
statement  line.) 

100  .P  .S  Wrong 

100  .P       Right  |     | 

110  .S       Right  I— . 

And  remember  to  keep  your  instructions  right  next  to  the 
colons,  no  spaces:  1    I 

100  LDA  #15    :         STA  5000    :    INY     Wrong  *""" 

100  LDA  #15:STA     5000:INY  Right 

You  have  now  learned  all  you  will  need  to  know  about  I 1 

LADS  to  create  and  assemble  the  examples  in  this  book.  What 

follows  are  additional,  more  advanced  features  of  LADS.  ,     , 
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More  Sophisticated  Features 

Here's  a  summary  of  all  the  commands  you  can  give  LADS: 


, ,  .P 


n 


.NP 


.NO 


.D  sourcefilename  objectfilename 


.FILE  filename 


•END  filename 


n 

H 
H 

n 

n 


.NS 


.H 


.NH 


Turn  on  printer  listing  of  object 
code  (.S  will  also  be  activated). 
Turn  off  printer  listing  of  object 
code. 

Turn  on  POKEs  to  memory.  Ob- 
ject code  is  stored  into  RAM  dur- 
ing assembly. 

Turn  off  POKEs  to  memory. 
Read  source  code  from 
sourcefilename  and  store  object 
code  to  objectfilename  on  disk 
following  assembly.  Use  no 
quotes  around  the  filenames  (.O 
will  also  be  activated). 
Necessary  when  you  use  .D. 
Links  one  source  file  to  the  next 
in  a  chain  so  that  they  will  all  as- 
semble together  as  a  single  large 
source  program  (end  the  chain 
with  .END  pseudo-op). 
Necessary  when  you  use  .D. 
Links  the  last  source  file  to  first 
source  file  in  a  chain.  If  you  are 
not  assembling  a  chain  of  files 
(rather,  are  assembling  from  a 
single  file),  you  must  still  give  its 
filename  as  the  .END  so  that  the 
assembler  knows  where  to  go  for 
the  second  pass.  Any  source  code 
must  have  .END  as  the  last  line 
in  the  program,  whether  the 
source  code  is  contained  within  a 
single  disk  file  or  spread  across  a 
multiple-file  chain. 
Turn  on  screen  listing  during 
assembly. 

Turn  off  screen  listing  during 
assembly. 

Turn  on  hexadecimal  output  for 
screen  or  printer  listing. 
Turn  off  hexadecimal  output  for 
screen  or  printer  listing  (as  a  re- 
sult, the  listings  are  in  decimal). 
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*  =  Set  program  counter  to  new  J     j 

address.  ' — ' 

+  Add  a  value  to  a  label. 

#"c  ASCII  value  of  character  c  (type-  i     i 

able  characters  only,  no  control  I ! 

codes). 

#<label  Least  significant  byte  (LSB)  of 

label.  '  [J 

#>label  Most  significant  byte  (MSB)  of 

label. 

.BYTE  N  N  Insert  single-byte  decimal  num- 

bers directly  into  object  code. 

.BYTE  "CCCCC  Insert  characters  directly  into  ob- 

ject code. 

A  Stable  Buffer 

The  pseudo-op  *=  is  always  the  first  item  in  any  ML  source 
code  program.  It  tells  the  computer  where  you  want  your  pro- 
gram stored.  However,  *=  can  be  used  within  a  program  too, 
to  change  the  storage  addresses  dynamically.  This  is  useful 
mainly  when  you  want  to  create  data  tables.  The  subprogram 
Tables  in  LADS  source  code  is  an  example  of  a  data  table.  (A 
subprogram  is  one  of  the  source  code  files  which,  when  linked 
together,  form  an  entire  ML  program.  We'll  describe  linking 
shortly.) 

Most  programmers  locate  an  ML  program's  tables,  non- 
zero page  variables,  buffers,  and  messages  at  the  high  end  of 
the  ML  program  the  way  LADS  does  with  its  Tables  sub- 
program. Since  you  don't  know  what  the  highest  RAM  ad- 
dress will  be  while  you're  writing  a  program,  you  can  force 
your  data  tables  to  always  reside  at  the  same  high  address  by 
setting  *  =  to  some  address,  perhaps  4K  above  the  starting  ad-  j     j 

dress.  This  gives  you  space  to  write  the  program  below  the  ta- 
bles without  moving  the  tables  up  higher  in  RAM  memory 
each  time  you  add  to  the  source  code.  |    | 

The  advantage  of  stabilizing  the  location  of  your  tables  is  '    ' 

that  you  can  easily  PEEK  them,  and  this  greatly  assists  debug- 
ging. You'll  always  know  exactly  where  buffers  and  variables 
are  going  to  end  up  in  memory  after  an  assembly — regardless 
of  the  changes  you  make  in  the  program.  After  your  program 
is  debugged  and  running  perfectly,  you  can  remove  the  *  = 
and  assemble  one  last  time,  closing  up  the  gap  between  the 
program  and  its  tables. 
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r™j  Here's  an  example.  Suppose  you  write: 

10  *=  $5000 
20  STA  BUFFER 
I"""!  30  *=  $6000 

40  BUFFER  .BYTE  00000000000000 

.  This  creates  an  ML  opcode  instruction  (STA  buffer)  at  ad- 

i     |  dress  $5000  (the  starting  address  of  this  particular  example  ML 

program),  but  places  the  buffer  itself  at  $6000.  When  you  add 
additional  instructions  after  STA  buffer,  the  location  of  the 
buffer  itself  will  remain  at  address  $6000.  This  means  that  you 
can  write  an  entire  program  (smaller  than  $1000  bytes)  with- 
out having  to  worry  that  the  location  of  the  buffer  is  being 
bumped  up  higher  each  time  you  add  new  instructions,  new 
code.  It's  high  enough  so  that  it  remains  stable  at  $6000,  and 
you  can  debug  the  program  more  easily.  You  can  always  check 
whether  something  is  being  correctly  sent  into  the  buffer  by 
just  looking  at  $6000  from  the  monitor. 

This  fragment  of  code  illustrates  two  other  features  of 
LADS.  You  can  use  the  pseudo-op  .BYTE  to  set  aside  some 
space  in  memory  (the  zeros  above  just  make  space  to  hold 
other  things  in  a  "buffer"  during  the  execution  of  an  ML  pro- 
gram). You  can  also  use  .BYTE  to  define  specific  numbers  in 
memory: 

.BYTE  65  66  67  68 

This  would  put  these  numbers  (always  use  decimal  num- 
bers between  0  and  255  with  this  pseudo-op)  into  memory  at  the 
location  of  the  .BYTE  instruction;  .BYTE  can  also  handle  text 
and  any  control  characters  (such  as  cursor  up)  except  screen 
clear.  An  easy  way  to  create  messages  that  you  want  to  print 
to  the  screen  is  to  use  the  .BYTE  pseudo-op  and  surround  text 
with  quotes: 

500  FIRSTLETTERS  .BYTE  "ABCD":.BYTE  0 

Then,  if  you  wanted  to  print  this  message,  you  could 
write: 

2  *=  $0B00 

5  LDY  #0 
10  LOOP  LDA  FIRSTLETTERS,Y 
20  BEQ  ENDMESSAGE 
30  STA  $0400, Y;  location  of  screen  RAM 
40INY 
50  JMP  LOOP 
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60  ENDMESSAGE  RTS;  finished  printout 
500  FIRSTLETTERS  .BYTE  "ABCD:.BYTE  0 

Note  that  using  the  second  set  of  quotation  marks  is  op- 
tional with  the  .BYTE  pseudo-op:  You  can  use  either  .BYTE  |    j 
"ABCD:.BYTE  0  or  .BYTE  "ABCD":.BYTE  0.  To  POKE  num-  L— 
bers  instead  of  characters,  just  leave  out  the  quotation  marks: 
.BYTE  10  15  75.  And  since  these  numeric  values  are  being                   j    j 
POKEd  directly  into  bytes  in  memory,  remember  that  they 
cannot  be  larger  than  255.  It's  like  BASIC'S  POKE  statement. 

Another  convenient  pseudo-op  looks  like  this:  #".  It  is 
used  when  you  want  to  specify  a  character  instead  of  a  num- 
ber for  immediate  addressing.  Say,  you  need  to  print  a  comma 
to  the  screen.  You  could  LDA  #44  (the  ASCII  code  for  a 
comma)  and  JSR  PRINT. 

But  if  you  don't  remember  that  a  comma  is  the  number  44 
in  the  ASCII  code,  and  you  don't  want  to  look  it  up,  LADS 
will  do  it  for  you.  Just  use  a  quotation  mark  after  the  #  sym- 
bol: LDA  #",  (followed  by  the  character  you're  after,  in  this 
case,  the  comma).  The  correct  value  for  the  character  will  be 
inserted  into  your  object  code.  To  print  the  letter  A,  you  would 
LDA  #"A  and  proceed  to  print  it  with  JSR  $FFD2.  Any  charac- 
ter you  type  after  the  quotation  mark  will  be  translated  into 
Commodore  ASCII  for  you.  Remember  that  the  #"  pseudo-op 
gives  you  the  screen  print  code,  not  the  screen  POKE  code.  If 
you  try  to  POKE  the  character  directly  on  the  40-column 
screen  with  STA  $0400,  you'll  get  a  shifted  version  of  what- 
ever character  you  requested.  Also,  #"  cannot  translate  cursor 
or  control  codes.  If  you  want  to  clear  the  screen,  you'll  need  to 
look  up  clear  screen  on  the  ASCII  chart  in  Appendix  G.  Clear 
screen  is  147,  so  you'd  use  LDA  #147:JSR  PRINT  to  accom- 
plish that.  jl 

Labels 

You  probably  noticed  in  the  example  above  how  many  English  j  j 
words  were  used  to  write  the  source  code:  FIRSTLETTERS,  ' — ' 
ENDMESSAGE,  LOOP.  These  are  used  pretty  much  as  vari- 
ables are  used  in  BASIC.  But  there  are  some  special  ad  van-  j  | 
tages  in  ML.  You  give  subroutines  names  rather  than  line  ' — ' 
numbers  and  that  helps  document  and  structure  your  program. 
Also,  these  words,  called  labels,  can  be  of  any  length.  And,  |  j 
unlike  BASIC  which  sees  only  the  first  two  characters  as  ^-^ 
significant,  each  label  is  entirely  significant  in  LADS.  So, 
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J""]  SCREEN  and  SCORE  are  distinct  labels  and  will  not  be 

confused. 


i    i 


With  LADS,  as  with  other  assemblers  that  permit  labels,  you 
need  not  refer  to  locations  in  memory  or  numeric  values  by 
using  numbers.  And  you'll  find  that  labels  are  far  easier  to  use. 

In  the  example  above,  line  10  starts  off  with  the  word 
LOOP.  This  means  that  you  can  use  the  word  LOOP  later  to 
refer  to  that  location  (see  line  50).  That's  quite  a  convenience: 
The  assembler  remembers  where  the  word  LOOP  is  used,  and 
you  need  not  refer  to  an  actual  memory  address;  you  can  refer 
to  the  label  instead.  This  kind  of  label  is  called  a  PC-type  (for 
Program  Counter)  or  address-type  label. 

The  other  type  of  label  is  defined  with  an  assembly 
convention  called  an  equate  (an  equal  sign).  This  is  quite  simi- 
lar to  the  way  that  BASIC  allows  you  to  assign  value  to 
words — it's  called  "assigning  variables"  when  you  do  it  in 
BASIC.  In  ML,  the  =  pseudo-op  works  pretty  much  the  way 
the  =  sign  does  in  BASIC,  and  these  "equates"  should  be  put 
at  the  very  start  of  an  ML  program.  (See  the  Defs  subprogram 
in  Appendix  D.)  Here's  an  example  of  equates,  located  at  the 
start  of  the  program,  in  lines  10  and  20: 

5    *=  $0B00 

10  SCREEN  =  $0400;  the  location  of  the  first  byte  in  RAM  of  the 

screen 
20  LETTERA  =  $41;  the  letter  A 

30  ; 

40  START  LDA  #LETTERA;  notice  "START"  (an  address-type 

label) 
50  STA  SCREEN;  40-COLUMN  MODE  ONLY 
60RTS 

Line  10  assigns  the  number  $0400  (1024  decimal)  to  the 
word  SCREEN.  Anytime  thereafter  that  you  use  the  word 
SCREEN,  LADS  will  substitute  $0400  when  it  assembles  your 
ML  program.  Line  20  "equates"  the  word  LETTERA  to  the 
number  $41.  So,  when  you  LDA  #LETTERA  in  line  40,  the 
assembler  will  put  a  $41  into  your  program.  (Notice  that,  like 
BASIC,  LADS  requires  equate  labels  to  be  a  single  word.  You 
couldn't  use  LETTER  A,  since  that's  two  words.) 

Line  30  is  just  a  REMark.  The  semicolon  tells  the  assem- 
bler that  what  follows  on  that  line  is  to  be  ignored.  Neverthe- 
less, blank  lines  or  graphic  dividers  like  line  30  can  help  to 
visually  separate  subroutines,  tables,  and  equates  from  your 
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actual  ML  program.  In  this  case,  we've  used  line  30  to  sepa-  |     I 

rate  the  section  of  the  program  which  defines  labels  (lines  10-  '— -' 
20)  from  the  program  proper  (lines  40-60).  All  this  makes  it 

easier  to  read  and  understand  your  source  code  later.  I    i 

Remember  that  in  BASIC  only  the  first  two  letters  of  a  * — ' 
variable  name  are  significant.  So,  SCREEN  and  SCORE  are 

taken  to  be  identical  variables.  LADS,  however,  offers  you  the  t    j 

advantage  of  seeing  all  letters  within  a  label  as  significant.  ' — ' 
SCREEN  and  SCREEN1  are  different  labels  to  LADS.  Of 
course,  you  cannot  use  the  same  label  to  mark  two  different 
addresses  or  values.  You  can't  use  the  same  label  for  two  dif- 
ferent equates  because  that  would  be  meaningless: 

SCREEN  =  $0400 
SCREEN  =  $0500 

Nor  should  you  define  two  different  addresses  within  the  ML 
program  using  the  same  label: 

10  LOOP  LDA  12 
20  BEQ  LOOP 

30  BNE  LOOP 

40  LOOP  RTS 

LADS  would  have  no  way  of  knowing,  in  lines  20  and  30, 
to  which  LOOP  you  intended  to  branch.  Don't  be  concerned, 
however,  about  keeping  track  of  what  labels  you  may  have  al- 
ready used.  When  you  assemble,  LADS  will  report  any  dupli- 
cate labels  and  tell  you  which  line  numbers  they  occurred  in. 
Then  you  can  easily  make  up  new  labels  where  necessary: 

40  LOOP1 

or 

40  NEWLOOP  ( 

Notice  that  lines  20  and  30,  although  they  both  contain  the  la-  ! — ' 

bel  LOOP,  do  not  cause  any  problems.  That's  because  they  are 
only  referring  to  the  label,  not  defining  it.  Labels  are  defined 
only  when  they  occur  as  the  first  thing  following  a  line  num- 
ber or  a  colon.  You  can  use  them  to  refer  to  the  defined  loca- 
tions or  values  as  often  as  you  want. 

A  related  labeling  error  will  also  be  flagged  by  LADS.  If 
LADS  reports  this  to  you: 

560  NUMBURS  LDA  12      UNDEFINED  LABEL 

you  would  need  to  look  at  line  560.  Usually,  this  is  caused  by 
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}— j  a  typo.  You  meant  to  type  NUMBERS  as  your  label  and  later 

!  referred  to  NUMBERS  (which  would  generate  an  UN- 

DEFINED LABEL  error  message  of  its  own).  Again,  just  LIST 

| — I  560,  and  type  560  NUMBERS  LDA  12  to  make  things  right. 

'  —  If  your  source  code  contains  a  label  with  nothing  follow- 

ing it: 

560  NUMBERS 


or 

570  NUMBERS:INY 


you'll  see  a  NAKED  LABEL  error  message.  Line  560  is  mean- 
ingless because  the  line  is  blank  following  the  label.  It  defines 
nothing.  Line  570  is  meaningless  for  the  same  reason  because 
a  colon  separates  statements  and  is  therefore  the  logical 
equivalent  of  an  end-of-line. 

Automatic  Math 

There  are  times  when  you  will  want  to  have  LADS  do  addi- 
tion for  you.  That's  where  the  +  pseudo-op  comes  in.  If  you 
write  "label +  1",  you  will  add  1  to  the  value  of  the  label. 
Here's  how  it  works: 

10  *=  $B00 

20  HIMEM  =  57;  top-of-memory  pointer. 

30  ; 

40  LDA  #0:STA  HIMEM:LDA  #$50:STA  HIMEM+1 

Here  we  are  putting  a  new  location  into  the  top-of-mem- 
ory pointer  which  the  computer  uses  to  decide  where  it  can 
store  things  in  bank  1.  (Doing  that  could  protect  an  ML  pro- 
gram which  resides  above  the  address  stored  in  this  pointer.) 
Like  all  pointers,  it  uses  two  bytes.  If  we  want  to  store  $5000 

|"j  into  this  pointer,  we  store  the  lower  half  (the  least  significant 

byte)  into  MEMTOP.  We'll  want  to  put  the  number  $50  into 
the  most  significant  byte  of  the  pointer — but  we  don't  need  to 

j""]  waste  time  making  a  new  label.  It's  just  one  higher  in  memory 

than  MEMTOP,  hence,  MEMTOP+1. 

You'll  also  want  to  use  the  +  pseudo-op  command  in 
constructions  like  this: 

10  *=  $B00 

15  SCREEN  =  $0400 

17; 

20  LDA  #32;  the  blank  character 
30  LDY  #0 
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40  START  STA  SCREEN,Y 

50  STA  SCREEN + 256, Y 

60  STA  SCREEN +512,Y 

70  STA  SCREEN + 768, Y 

80 INY  1_J 

90  BNE  START 

This  is  the  fastest  way  to  fill  memory  with  a  given  byte.  i    i 

In  this  case  we're  clearing  out  the  screen  RAM  by  filling  it  > — I 

with  blanks  (in  the  40-column  mode  only).  As  you  can  see,  it's 
easy  to  indicate  multiples  of  256  by  just  adding  them  to  the 
label  SCREEN.  Any  time  you  want  to  add  a  number  to  a  label, 
just  attach  +  and  the  number,  but  don't  leave  any  spaces  be- 
tween the  label,  the  +  and  the  number: 

LDA  (LABEL  +  22),Y    Wrong 
LDA  (LABEL +22),Y      Right 

A  similar  pseudo-op  command  is  the  #<.  This  refers  to 
the  least  significant  byte  of  a  label.  For  example, 

10  *=  $0B00 

20  SCREEN  =  $0400 

25  SCREENPOINTER  =  $FB 

30  ; 

40  LDA  #<SCREEN;  LSB  (least  significant  byte  of  the  label 

SCREEN,  $00) 
50  STA  SCREENPOINTER 
60  LDA  #>SCREEN;  MSB  (most  significant  byte  of  the  label 

SCREEN,  $04) 
70  STA  SCREENPOINTER +1 

Line  40  is  the  equivalent  of  LDA  #$00  and  line  60  is  the 
equivalent  of  LDA  #$04,  but  using  #<  and  #>  allows  you  to 
break  a  label  into  its  bytes  conveniently  without  having  to 
know  the  actual  value  of  the  label. 

You'll  find  this  technique  used  several  times  in  the  LADS 
source  code.  It  puts  the  LSB  (least  signficant  byte)  or  the  MSB 
(most  signficant  byte)  of  a  label  into  the  LSB  or  MSB  of  a 
pointer  which,  in  effect,  creates  the  pointer  (makes  it  point  to 
the  label).  In  the  example  above,  we  want  to  set  up  a  pointer 
that  will  hold  the  address  of  the  screen  RAM.  We've  called 
this  pointer  SCREENPOINTER,  and  we  want  to  put  $00  (the 
LSB  of  SCREEN)  into  SCREENPOINTER.  So,  we  extract  the 
LSB  of  SCREEN  in  line  40  by  using  #  combined  with  the  less- 
than  symbol.  We  complete  the  job  of  creating  the  pointer  by 
using  the  greater- than  symbol  to  fetch  the  MSB: 
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j—j  60  LDA  #>SCREEN:STA  SCREENPOINTER+1 

Notice  that  these  symbols  must  be  attached  to  the  label; 
_  no  space  is  allowed.  For  example,  LDA  #>  SCREEN  would  cre- 

ij  ate  problems.  This  LSB  or  MSB  extraction  from  a  label  is 

something  you'll  need  to  do  from  time  to  time.  The  #<  and 

#>  pseudo-ops  do  it  for  you. 


n 


Chained  Files 

LADS  has  two  distinct  personalities.  So  far  we've  been 
discussing  LADS  as  it  comes  out  of  the  can,  its  native  state 
when  you,  or  the  Loader,  BLOAD  it  in  from  disk.  It  assembles 
and  stores  the  results  on  screen  (with  .S),  in  RAM  in  bank  15 
(.0),  or  to  the  printer  (.P).  Let's  call  this  mode  RAMLADS 
since  it  works  exclusively  in  RAM. 

This  personality  is  most  useful  for  testing  routines  which 
are  short  enough  for  the  source  code  to  fit  between  $1C00  (the 
default  start  of  BASIC  text  area)  and  $2710  where  the  LADS 
assembler  starts  in  memory.  But  when  source  code  gets  fairly 
large,  it  will  either  overwrite  LADS,  or  LADS  itself,  which 
stores  labels  during  assembly  moving  down  from  $2710,  will 
overwrite  the  source  code.  In  short,  assembling  source  code 
about  IK  or  longer  will  cause  the  source  code  and  LADS  to 
compete  for  the  same  memory  space  and  interfere  with  each 
other. 

For  these  larger  programs,  you  should  store  your  source 
code  on  disk  and,  by  using  the  .D  pseudo-op  at  the  start  of 
the  source  code,  tell  LADS  to  look  on  the  disk  drive  for  ma- 
terial to  assemble.  (Cassette  tape  users  will  not  be  able  to 
switch  DISKLADS  on  with  the  .D  pseudo-op.  They  must  use 
RAMLADS  and  then  save  object  code  to  tape  via  the  monitor. 
See  SAVE  in  Chapter  3.) 

When  you  insert  .D  into  your  source  code,  LADS  trans- 
forms itself;  it  modifies  its  actual  structure  and  turns  its  atten- 
tion to  the  disk  drive  for  source  code.  Let's  call  this  second 
personality  DISKLADS.  DISKLADS  offers  several  benefits 
when  large  programs  are  involved. 

It  is  sometimes  convenient  to  create  several  source  code 
subprograms,  to  break  the  ML  program  source  code  into  sev- 
eral pieces.  An  example  of  this  is  the  LADS  source  code  itself. 
It's  divided  into  a  number  of  program  files:  Array,  Equate, 
Math,  Pseudo,  and  so  on.  This  way,  you  don't  need  to  load 
the  entire  source  code  into  the  computer's  memory  when  you 
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just  want  to  work  on  a  particular  part  of  it.  It  also  allows  you 
to  assemble  source  code  far  larger  than  could  fit  into  available 
RAM.  For  example,  LADS  itself,  with  all  its  comments,  has 
source  code  which  is  72K  large.  By  the  way,  this  creates  an  in- 
teresting ratio  between  source  and  object  code:  After  assembly, 
LADS  boils  down  to  about  5K  of  runnable  object  code. 

When  using  DISKLADS,  you  link  the  separate  source 
code  files  together  into  a  chain.  In  the  last  line  of  each  sub- 
program you  want  to  link,  you  put  the  linking  pseudo-op 
.FILE  NAME  (use  no  quotes)  to  tell  the  assembler  which  sub- 
program to  assemble  next.  Subprograms,  chained  together  in 
this  fashion,  will  be  treated  as  if  they  were  one  large  program. 

The  final  subprogram  in  the  chain  ends  with  the  special 
pseudo-op  .END  NAME,  and  this  time  the  name  is  the  file- 
name of  the  first  of  the  subprograms,  the  subprogram  which 
begins  the  chain.  It's  like  stringing  pearls  and  then,  at  the  end, 
tying  thread  so  that  the  last  pearl  is  next  to  the  first,  to  form  a 
necklace. 

Notice  however  that  when  you  turn  on  DISKLADS  with 
.D,  you  always  need  to  include  the  .END  pseudo-op,  even  if 
you  are  assembling  from  just  one,  unlinked,  source  code  file. 
In  that  case  (where  you're  working  with  a  solo  file),  you  don't 
use  any  linking  .FILE  pseudo-ops.  Instead,  refer  the  file  to  it- 
self with  .END  NAME  where  you  list  the  solo  file's  name. 

Here's  an  illustration  of  how  three  subprograms  would  be 
linked  to  form  a  complete  program: 

5  *-  2816 

10  ;  FIRSTSOURCE-first  program  in  chain 
20  ;its  first  line  must  contain  the  start  address 
30  .D  FIRSTSOURCE  FIRSTOBJECT 

40  LDA  #20  ,     , 

50  STA  $0400  LJ 

60  .FILE  SECOND 

Then  you  save  this  subprogram  to  disk  (it's  handy  to  let  ,    , 

the  first  remark  line  in  each  subprogram  identify  the  sub-  LJ 

program's  filename): 

DSAVE  "FIRSTSOURCE  1     I 

Next,  you  create  SECOND,  the  next  link  in  the  chain.  But 
here,  you  use  no  starting  address;  you  enter  no  *=  since  only 
one  start  address  is  needed  for  any  program:  j j 
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10  ;  SECOND  (IT'S  A  GOOD  IDEA  TO  PUT  THE  NAME  OF 

THE  FILE  HERE) 
20  INY:INX:DEY:DEX 
30  .FILE  THIRD 

DSAVE  "SECOND 


Now  write  the  final  subprogram,  ending  it  with  the  clasp 
P~j  pseudo-op  .END  NAME  which  links  this  last  subprogram  to 

the  first: 

10 ;  THIRD 

20  LDA  #191:STA  $0400 

30  .END  FIRSTSOURCE 

DSAVE  "THIRD 

When  you  want  to  assemble  this  linked  source  code,  if  the 
first  file  in  the  chain  isn't  already  in  RAM  memory,  you 
DLOAD  "FIRSTSOURCE  to  show  LADS  the  .D.  Then  press 
Fl  or  type  SYS  10000,  and  LADS  will  take  it  from  there. 

The  format  for  .D  is 

.D  sourcename  objectnatne 

RAMLADS  will  see  the  .D  and  change  itself  into 
DISKLADS.  After  you've  once  transformed  RAMLADS  into 
this  new  personality,  it  will  locate  source  code  on  the  disk  files 
and  store  object  code  to  bank  1.  After  it  has  finished  the 
assembly,  LADS  will  save  (with  replace)  the  object  code  to  the 
disk  under  the  name  you  gave  for  the  object  file  after  .D.  In 
our  three-file  example  above,  LADS  will  save  a  file  named 
FIRSTOBJECT.  Finally,  LADS  will  reload  itself  and,  thus, 
change  back  into  its  RAMLADS  personality.  In  other  words, 
LADS  responds  appropriately  if  there  is  .D  in  the  source  code. 
If  it  doesn't  find  one,  it  remains  RAM-oriented. 

DISKLADS  operates  somewhat  differently  from 
RAMLADS.  DISKLADS  always  switches  on  the  .0  pseudo-op 
and  saves  the  object  code  to  RAM  in  bank  1.  Thus  (unlike 
RAMLADS  where  you  have  to  find  a  safe  place  to  store  object 
code  when  using  .6),  with  DISKLADS  you  can  create  an  ML 
program  that  resides  anywhere  between  $0000  and  $FFFF 
(0-65535  decimal),  and  it  will  not  interfere  with  LADS  or 
BASIC  or  anything  else  since  it's  being  stored  into  the  pure 
RAM  of  bank  1.  (Remember,  though,  that  extremely  low 
RAM— $0000-$03FF— is  shared  between  banks.)  Thus,  your 
source  and  object  codes  can  be  huge,  as  large  as  a  RAM  bank. 
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LADS  also  prints  the  starting  address  in  hex  of  each  file, 
and  DISKLADS  prints  LOADING  when  bringing  the  file  in 
from  disk,  and  blanks  the  line  while  actually  assembling. 

Rules  for  LADS 

Here  are  the  rules  you  need  to  follow  when  writing  ML  for 
LADS  to  assemble: 

1.  In  general,  all  equate  labels  (labels  using  an  equal  sign)  should 
be  defined  at  the  start  of  your  program. 
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Then,  when  assembly  is  finished,  the  object  code  is  stored  I    j 

to  disk  under  the  name  you  gave  with  .D  (FIRSTOBJECT  in  ' — ' 

the  example  above).  Use  no  quotation  marks  around  filenames 
for  .D  or  .END  or  .FILE.  If  you  forget  to  put  .END  or  .FILE  [ 

when  you've  used  .D,  LADS  will  remind  you  that  it  now  '"-J 

needs  these  linking  commands.  If  you  want  to  go  back  to 
assembling  smaller  routines  with  RAMLADS,  just  start  typing  j    I 

in  source  code,  but  avoid  .D.  LADS  changes  personality  only  ' — ' 

when  triggered  with  .D.  Naturally,  you  don't  use  .FILE  or 
.END  with  RAMLADS. 

When  DISKLADS  has  finished  assembling  the  example 
above  by  the  disk  method,  there  will  be  an  ML  program  on 
disk  called  FIRSTOBJECT.  You  can  BLOAD  it  and  SYS  2816 
(that  was  the  start  address  we  gave  this  program),  and  the 
newly  assembled  ML  program  will  execute.  Note  that  even 
though  LADS  saved  it  to  disk  from  bank  1,  it  will  BLOAD  into 
bank  0  unless  you  specify  otherwise  with  the  BLOAD  com- 
mand. Also,  DISKLADS  always  does  a  Save-with-Replace, 
and  this  allows  you  to  keep  testing  versions  without  having  to 
rename  each  one.  If  you  want  to  preserve  a  version,  be  sure  to 
RENAME  it  before  assembling;  it  will  be  replaced  at  the  end 
of  the  assembly.  You  can  always  stop  any  assembly  at  any 
time  with  the  RUN/STOP  key.  If  a  file  is  being  loaded  when 
you  press  RUN/STOP,  just  hold  down  the  RUN/STOP  key 
until  disk  access  finishes.  Since  no  object  code  is  saved  to  disk 
until  assembly  is  finished,  any  previous  version  of  object  code 
will  remain  unreplaced  on  the  disk. 

While  LADS  is  assembling  in  either  mode,  it  will  report 
any  errors  by  ringing  the  bell,  displaying  the  line  number 
wherein  the  error  occurred,  and  snowing  the  offending  source 
code  in  reverse  video.  After  assembly,  it  will  tell  you  the  total  i    i 

number  of  errors,  if  any.  ! — ' 
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While  this  isn't  absolutely  necessary  for  labels  with 
numbers  above  255  (see  SCREEN  in  the  example  below),  it 
is  the  best  programming  practice.  It  makes  it  easier  for  you 
to  modify  your  programs  and  simplifies  debugging.  LADS 
itself  locates  all  its  equate  labels  in  the  subprogram  Defs 
(Appendix  D),  the  first  subprogram  in  its  chain  of  source 
code  files. 

What's  more,  it  is  necessary  that  any  equate  label  with 
a  value  lower  than  256  be  defined  before  any  ML  mnemon- 
ics reference  that  label.  So,  to  be  on  the  safe  side,  just  get 
into  the  habit  of  putting  all  equate  labels  at  the  very  start  of 
your  programs: 

10  *  =  2816 

20  ARRAYPOINTER  =  $FB;  (251  decimal),  a  zero  page  address 
30  OTHERPOINTER  =  $FD;  (253  decimal),  another  zero  page 
address 

40  ; 

50  LDY  #0:LDA  $1 

60  STA  ARRAYPOINTER,Y 

70  SCREEN  =  $0400 

Notice  that  it's  permissible  to  define  the  label 
SCREEN  anywhere  in  your  program.  It's  not  a  zero  page 
address.  You  do  have  to  be  careful,  however,  with  zero  page 
addresses  (addresses  lower  than  255).  So  most  ML  pro- 
grammers make  it  a  habit  to  define  all  their  equates  at  the 
start  of  their  source  code. 
2.  Put  only  one  pseudo-op  on  a  line. 

Don't  use  a  colon  to  put  two  pseudo-ops  on  a  single 
line: 

10  *=  864 

20 .0:.NH  Wrong 

30 .0  Right 

40  .NH  Right 

The  main  exception  to  this  is  the  .BYTE  pseudo-op. 
Normally,  you'll  set  up  messages  with  a  zero  at  their  ends 
to  delimit  them,  to  show  that  the  message  is  complete. 
When  you  delimit  messages  with  a  zero,  you  don't  need  to 
know  the  length  of  the  message;  you  just  branch  when  you 
come  upon  a  zero: 

10  *=  2816 

20  SCREEN  =  $0400 

30  ; 
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40  LDY  #0 

50  LOOP  LDA  MESSAGE, Y:BEQ  END;  loading  a  zero  signals 

end  of  message. 
60  STA  SCREEN, Y:INY:  JMP  LOOP;  LADS  ignores  spaces  after 

colon. 

70  ; message  area  here 

80  MESSAGE  .BYTE  "PRINT  THIS  ON  SCREEN":.BYTE  0 

Any  embedded  pseudo-ops  like  +  or  =  or  #>  can  be 
used  on  multiple-statement  lines.  The  pseudo-ops  which 
should  be  on  a  line  by  themselves  are  the  I/O  (input/ 
output)  instructions  which  direct  communication  to  disk, 
screen,  or  printer,  like  .P,  .S,  .D,  .END,  and  so  forth.  It's 
also  important  to  put  .D  at  the  start  of  your  source  code. 

Generally,  it's  important  that  you  space  things  cor- 
rectly. Avoid  leading  spaces  before  semicolons  (see  lines  50 
and  60  above  for  correct  use  of  semicolons.  Everything  on  a 
line  following  a  semicolon  is  ignored,  so  spaces  after  the 
semicolon  are  fine.  Also,  if  you  wrote  SCREEN  =  864, 
LADS  would  think  that  your  label  was  screen=  instead  of 
screen.  So  you  need  that  space  between  the  label  and  the 
equal  sign.  Likewise,  you  need  to  put  a  single  space  between 
labels,  mnemonics,  and  arguments: 

LOOP  LDA  MESSAGE 

Running  them  together  will  confuse  LADS. 

LOOPLDA  MESSAGE 

and 

LOOP  LDAMESSAGE 

are  wrong. 

Spaces  within  remarks  are  ignored.  In  fact,  LADS  ig- 
nores everything  within  remarks,  everything  following  a  ] j 

semicolon  on  a  line  (see  line  70).  Thus,  the  semicolon 
should  come  after  anything  you  want  assembled.  You 

couldn't  rearrange  line  50  above  by  putting  the  BEQ  END  | j 

after  the  remark  message.  It  would  be  ignored  because  it 
followed  the  semicolon. 

Errant  spacing,  while  it  sometimes  won't  assemble  j j 

correctly,  is  generally  not  fatal.  LADS  can  ignore  some  spac- 
ing errors  and  will  report  error  messages  when  it  finds  oth- 
ers. LOOPLDA  would  result  in  an  UNDEFINED  LABEL  j_J 
error  message,  for  example.  But  it's  a  good  idea  to  get  into 
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(""~"}  the  habit  of  putting  colons  and  semicolons  right  up  against 

source  code,  with  no  extra  spaces. 

When  using  the  text  form  of  .BYTE,  it's  up  to  you 
j"" "J  whether  you  use  a  close  quote: 

50  MESSAGE  .BYTE  "PRINT  THIS"  Right 

60  MESSAGE  .BYTE  "PRINT  THIS    Also  right 

3.  The  first  character  of  any  label  must  be  a  letter,  not  a  number. 
LADS  knows  when  it  comes  upon  a  label  because  a 
number  starts  with  a  number;  a  label  starts  with  a  letter  of 
the  alphabet: 

10  *-  $B00 
20  LABEL  =  255 
30  LDA  LABEL 
40  LDA  255 

Lines  30  and  40  accomplish  the  same  thing  and  are 
correctly  written.  It  would  confuse  LADS,  however,  if  you 
wrote 

20  5LABEL  =  255    Wrong 

since  the  number  5  at  the  start  of  the  word  LABEL  would 
signal  the  assembler  that  it  had  come  upon  a  number,  not  a 
label.  You  can  use  numbers  anywhere  else  in  a  label 
name — just  don't  put  a  number  at  the  start  of  the  name. 
Also  avoid  using  symbols  like  #,  <,  >,  and  *,  and  other 
punctuation,  shifted  letters,  or  graphics  symbols  within  la- 
bels. Stick  with  ordinary  alphanumerics: 

10  5LABEL     Wrong 
20LABEL15   Right 
30  "LABEL*   Wrong 

f~*"j  4.  Move  the  program  counter  forward,  never  backward. 

The  *=  pseudo-op  should  be  used  to  make  space  in 
memory.  If  you  set  the  PC  below  its  current  address,  you 
would  be  writing  over  previously  assembled  code: 

10  *=  $B00 

20  LDA  #15 

30  *=  $B50  Right 

10  *=  $B10 

20  LDA  #15 

30  *=  $B00  Wrong;  you'll  assemble  right  over  the  LDA  #15. 
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Modifying  LADS  jj 

LADS  is,  of  course,  itself  a  machine  language  program.  This 
book  and  the  optional  disk  include  all  the  source  code  for 

LADS.  It's  heavily  commented,  so  you  can  understand  how  j | 

the  assembler  works  and  locate  things  you  want  to  modify. 

To  change  LADS,  to  customize  your  assembler,  you'll 
have  to  have  typed  in  all  the  source  code  (or  purchased  this  j 

book's  disk).  Be  sure  to  make  a  couple  of  backup  disks  in  case 
the  first  attempts  at  improvements  are  less  than  entirely 
successful.  Then,  modify  one  or  more  of  the  subprograms  such 
as  Eval  or  Indisk,  and  SCRATCH  the  earlier  subprogram(s)  on 
disk  and  BLOAD  or  BOOT  LADS.  For  additional  safety,  RE- 
NAME "LADS"  TO  "OLDLADS"  so  that  you'll  have  a  work- 
ing version  of  the  assembler  for  any  emergencies.  Next, 
DLOAD  "DEFS128",  which  is  LADS's  starting  subprogram, 
and  SYS  10000.  LADS  will  then  create  a  new  version  of  itself 
with  your  modifications  incorporated  and  save  it  to  disk  under 
the  name  LADS. 

LADS  can  assemble  its  own  source  code  because,  to  an 
assembler,  source  code  is  source  code.  It  doesn't  have  any 
problems  with  self-regeneration  nor  does  it  harbor  any 
proscriptions  against  what  is,  after  all,  the  ethically  ambiguous 
act  of  cloning. 
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Commodore  128  Memory 


Map 


0 

$00 

1 

$01 

2 

$02 

3-4 

$03-$04 

5 

$05 

6 

$06 

7 

$07 

8 

$08 

45-46 

$2D-$2E 

0-255  ($0000-$00FF)  Zero  Page 

The  numbers  in  brackets  ([  ])  following  each  entry  are  the  corresponding  Commodore  64  loca- 
tions. An  asterisk  in  brackets  ([•])  indicates  that  the  location  is  identical  in  the  64.  All  addresses 
are  listed  in  both  decimal  and  hexadecimal 

8502  I/O  port  data  direction  register  [*] 

8502  I/O  port  data  register  [*] 

Bank  value  storage  for  JMPFAR  and  JSRFAR 

Program  counter  storage  for  JMPFAR  and  JSRFAR 

Status  register  storage  for  JMPFAR  and  JSRFAR 

Accumulator  storage  for  JMPFAR  and  JSRFAR 

X  register  storage  for  JMPFAR  and  JSRFAR 

Y  register  storage  for  JMPFAR  and  JSRFAR 

Pointer  to  start  of  BASIC  program  text  (in  bank  0) 

[43-44/$2B-$2C] 

47-48         $2F-$30       Pointer  to  start  of  variables  (in  bank  1) 
[45-46/$2D-$2E] 

49-50         $31-$32       Pointer  to  start  of  arrays  (in  bank  1) 
[47-48/$2F-$30] 

51-52         $33-$34       Pointer  to  start  of  free  memory  (in  bank  1) 
[49-50/$31-$32] 

53-54         $35-$36       Pointer  to  bottom  of  dynamic  string  storage  (in  bank 
1)  [51-52/$33-$34] 

55-56         $37-$38       Pointer  to  most  recently  used  string  (in  bank  1) 
[53-54/$35-$36] 

57-58         $39-$3A      Pointer  to  top  of  dynamic  string  storage  (in  bank  1) 
[55-56/$37-$38] 

59-60         $3B-$3C      Current  BASIC  line  number  [57-58/$39-$3A] 

61-62         $3D-$3E      Pointer  to  current  BASIC  text  character 
[122-123/$7A-$7B] 

65-66         $41-$42       Current  DATA  line  number  [63-64/$3F-$40] 

67-68         $43-$44       Pointer  to  current  DATA  item  [65-66/$41-$42] 

71-72         $47-$48       Pointer  to  current  BASIC  variable  name 
[69-70/$47-$48] 

73-74         $49-$4A      Pointer  to  current  variable  contents 

99-104       $63-$68       Floating-point  accumulator  1  (FAC1) 
[97-102/$61-$66] 

106-111     $6A-$6F      Floating-point  accumulator  2  (FAC2) 
[105-1 10/$69-$6E] 

125-126     $7D-$7E      Pointer  into  BASIC  runtime  stack  at  $0800-$09FF 

144  $90  Status  byte  for  tape  and  serial  I/O  [*] 

145  $91  STOP  key  flag  (127  =  RUN/STOP  key  pressed)  [*] 
152            $98              Number  of  files  currently  opened  [*] 
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153 

$99 

154 

$9A 

157 

$9D 

160-162 

$A0-$A2 

172-173 

$AC-$AD 

174-175 

$AE-$AF 

178-179 

$B2-$B3 

183 

$B7 

184 

$B8 

185 

$B9 

186 

$BA 

187-188 

$BB-$BC 

193-195 

$C1-$C2 

195-196 

$C3-$C4 

198 

$C6 

199 

$C7 

200-201 

$C8-$C9 

202-203 

$CA-$CB 

204-204 

$CC-$CD 

208 

$D0 

211 

$D3 

212 

$D4 

213 

$D5 

215 

$D7 

228 

$E4 

229 

$E5 

230 

$E6 

231 

$E7 

232 

$E8 

u 
u 


u 


Current  input  device  [*]  1     j 

Current  output  device  [*]  ' — I 

Kernal  message  flag  (192  =  Kernal  control  and  error 

messages  displayed,  128  =  only  control  messages 

displayed,  64  =  only  error  messages  displayed,  0  =  ji 

no  messages  displayed)  [*] 

Software  jiffy  clock  [*] 

Working  pointer  for  LOAD,  SAVE,  and  VERIFY  [*] 

Ending  address  for  LOAD,  SAVE,  and  VERIFY  [*] 

Pointer  to  cassette  buffer  [*] 

Length  of  current  filename  [*] 

Current  logical  file  number  (channel)  [*] 

Current  secondary  address  [*] 

Current  device  number  [*] 

Address  of  current  filename  [*] 

Starting  address  for  SAVE,  LOAD,  and  VERIFY  [*] 

Starting  address  of  memory  to  be  loaded  or  saved  to 

tape  [*] 

Also  used  as  a  pointer  during  block  memory  moves 

Bank  for  current  LOAD,  SAVE,  or  VERIFY  operation 

Bank  where  current  filename  is  found 

Pointer  to  RS-232  input  buffer  [247-248/$F7-$F8] 

Pointer  to  RS-232  output  buffer  [249-250/$F9-$FA] 

Pointer  to  current  keyboard  lookup  table  (in  ROM) 

[243-244/$F3-$F4] 

Number  of  characters  in  keyboard  buffer  [198/$C6] 

Current  SHIFT,  CONTROL,  Commodore,  and  ALT 

key  status  [653/028D] 

Matrix  coordinate  of  current  key  pressed  [203/$CB] 

Matrix  coordinate  of  last  key  pressed  [197/$C5] 

Screen  width  flag  (0  =  40  columns,  128  =  80 

columns) 

216  $D8  Text/graphics  mode  flag  for  40-column  screen: 

224  =  graphic  4  (split  multicolor  bitmapped  and 

text) 
160  =  graphic  3  (multicolor  bitmapped) 
96  =  graphic  2  (split  bitmapped  and  text) 
32  =  graphic  1  (bitmapped) 
0  =  graphic  0  (text) 

217  $D9  Shadow  register  for  CHREN  bit  of  location  $01  (4  = 

I/O  block  at  $D000-$DFFF,  0  =  character  ROM  at 

$D000-$DFFF) 
224-225     $E0-$E1       Pointer  to  current  text  screen  line 

[209-210/$Dl-$D2]                                                                     ■     , 
226-227     $E2-$E3      Pointer  to  current  color  (attribute)  line  | j 

[243-244/$F3-$F4] 

Bottom  line  of  current  window 

Top  line  of  current  window 

Left  margin  of  current  window 

Right  margin  of  current  window 

Line  for  input  [201/$C9] 
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233 

$E9 

234 

$EA 

235 

$EB 

236 

$EC 

237 

$ED 

238 

$EE 

243 

$F3 

244 

$F4 

245 

$F5 

247 

$F7 

248 

$F8 

251-254 

$FB-$FE 
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Starting  logical  column  for  input  [202/$CA] 
Ending  logical  column  for  input  [200/$C8] 
Current  cursor  line  [214/$D6] 
Current  cursor  column  [211/$D3] 
Maximum  number  of  lines  in  screen 
Maximum  number  of  columns  in  a  line  [213/$D5] 
Reverse  mode  flag  (if  nonzero,  characters  are  printed 
in  reverse  video)  [199/$C7] 

Quote  mode  flag  (if  nonzero,  quote  mode  is  in  effect) 
[212/$D4] 

Insert  mode  flag  (if  nonzero,  number  of  inserts  pend- 
ing) [216/$D8] 

Enable/disable  character  set  switching  with  SHIFT- 
Commodore  (128  =  disable  switching,  0  =  enable 
switching)  [657/$0291] 

Enable/disable  screen  scrolling  (128  =  no  scrolling, 
0  =  allow  scrolling) 
Unused  [251-254/$FB-$FE] 

256-511  ($0100-$01FF)  Page  One— System  Stack 

512-1023  ($0200-$03FF)  Common  RAM  Vectors  and  Routines 

BASIC  input  buffer  (161  bytes) 

[512-600/$0200-$0258] 

INDFET  routine  to  get  a  character  from  any  bank 

INDSTA  routine  to  store  a  character  in  any  bank 

INDCMP  routine  to  compare  characters  in  any 

banks 

JSRFAR  routine  to  jump  to  a  subroutine  in  any 

bank  and  return  to  the  calling  bank 

JMPFAR  routine  to  jump  to  a  routine  in  any 

bank  without  return 

IERROR  vector  to  BASIC  error  message  routine 

[*] 

IMAIN  vector  to  main  BASIC  immediate  mode 

loop  [*] 

ICRNCH  vector  to  routine  that  tokenizes  a  line 

of  BASIC  text  [*] 

IQPLOP  vector  to  routine  that  lists  a  token  as 

characters  [*] 

IGONE  vector  to  routine  that  executes  a  BASIC 

statement  token  [*] 

IEVAL  vector  to  routine  that  evaluates  an 

arithmetic  expression  [*] 

Vector  to  routine  that  tokenizes  a  two-byte  token 

Vector  to  routine  that  lists  a  two-byte  token  as 

characters 

Vector  to  routine  that  executes  a  two-byte  BASIC 

statement  token 

CINV  vector  to  IRQ  handler  routine  [*] 


512-673 

$0200-$02Al 

674-686 

$02A2-$02AE 

687-701 

$02AF-$02BD 

702-716 

$02BE-$02CC 

717-738 

$02CD-$02E2 

739-761 

$02E3-$02F9 

768-769 

$0300-$0301 

770-771 

$0302-$0303 

f—1 

I    1 

772-773 

$0304-$0305 

774-775 

$0306-$0307 

P") 

1      \ 

776-777 

$0308-$0309 

n 

778-779 

$030A-$030B 

780-781 

$030C-$030D 

782-783 

$030E-$030F 

n 

784-785 

$0310-$0311 

788-789 

$0314-$0315 
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790-791 
792-793 
794-795 
796-797 
798-799 
800-801 
802-803 
804-804 
806-807 
808-809 
810-811 
812-813 
816-817 
818-819 
842-851 
866-875 

876-885 

886-895 

896-926 

902 

927-938 
939-950 
951-959 

960-968 

969-977 


$0316-$0317      CBINV  vector  to  BRK  handler  routine  [*] 
$0318-$0319      NMINV  vector  to  NMI  handler  routine  [*] 
$031A-$031B     IOPEN  vector  to  the  Kernal  OPEN  routine  [*] 
$031C-$031D     ICLOSE  vector  to  the  Kernal  CLOSE  routine  [*] 
$031E-$031F      ICHKIN  vector  to  the  Kernal  CHKIN  routine  [*] 
$0320-$0321      ICKOUT  vector  to  the  Kernal  CKOUT  routine  [*] 
$0322-$0323      ICLRCH  vector  to  the  Kernal  CHRCH  routine  [*] 
$0324-$0325      IBASIN  vector  to  the  Kernal  BASIN  routine  [*] 
$0326-$0327      IBSOUT  vector  to  the  Kernal  BSOUT  routine  [*] 
$0328-$0329      ISTOP  vector  to  the  Kernal  STOP  routine  [*] 
$032A-$032B     IGETIN  vector  to  the  Kernal  GETIN  routine  [*] 
$032C-$032D     ICLALL  vector  to  the  Kernal  CLALL  routine  [*] 
$0330-$0331       ILOAD  vector  to  the  Kernal  LOAD  routine  [*] 
$0332-$0333      ISAVE  vector  to  the  Kernal  SAVE  routine  [*] 
$034A-$0353      Keyboard  input  buffer  [631-640/$0277-$0280] 
$0362-036B        Table  of  logical  file  numbers 

[601-610/$0259-$0262] 
$036C-$0375      Table  of  device  numbers  for  open  files 

[611-620/$0263-$026C] 
$0376-$037F      Table  of  secondary  addresses  for  open  files 

[621-630/$026D-$0276] 
$0380-$039E      Routine  to  get  next  character  of  BASIC  program 

text  from  bank  0  (CHRGET)  [115-138/$73-$8A] 
$0386  Entry  point  in  CHRGET  to  retrieve  previous 

character  (CHRGOT)  [121/$79] 
$039F-$03AA     Indirect  fetch  from  bank  0  for  ROM  routines 
$03AB-$03B6     Indirect  fetch  from  bank  1  for  ROM  routines 
$03B7-$03BF      Fetch  from  bank  1  for  ROM  routines;  uses 

$24-$25  as  pointer 
$03C0-$03C8     Fetch  from  bank  0  for  ROM  routines;  uses 

$26-$27  as  pointer 
$03C9-$03D1     Fetch  from  bank  0  for  ROM  routines;  uses 

$3D-$3E  as  pointer 


1024-2047  ($0400-$07FF)  Bank  0:  40-Column  Text  Screen  Memory 
($0800-$1BFF)  Bank  0:  BASIC  and  Kernal  Working 


2048-7167 
Storage 

2048-2559 

2560-2561 

2562 

2563 

2565-2566 

2567-2568 
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$0800-$09FF      BASIC  stack:  pointers  for  DO-LOOP,  BEGIN- 
BEND,  etc. 

$0A00-$0A01     System  restore  vector  (points  to  BASIC  warm- 
start  routine) 

$0A02  Flag  to  indicate  that  system  vector  has  been 

initialized 

$0A03  PAL/NTSC  flag  (0  =  NTSC  video,  1  =  PAL 

video)  [678/$02A6] 

$0A05-$0A06     Pointer  to  bottom  of  memory  used  for  pro- 
gram text  (in  bank  0)  [641-642/$0281-$0282] 

$OA07-$OA08     Pointer  to  top  of  memory  used  for  variables 
(in  bank  1)  [643-644/$0283-$0284] 
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2576  $0A10  RS-232  control  register  [659/$0293] 

2577  $0A11  RS-232  command  register  [660/$0294] 
2578-2579     $0A12-$0A13     RS-232  user-defined  baud  rate 

[661-662/$0295-$0296] 
2580  $0A14  RS-232  status  register  [663/$0297] 

2582-2583      $0A16-$0A17     RS-232  baud  timing  constant  value 

[665-666/$0299-$029A] 

2584  $0A18  Index  to  last  character  in  the  RS-232  input 

buffer  [667/$029B] 

2585  $0A19  Index  to  first  character  in  the  RS-232  input 

buffer  [668/$029C] 

2586  $0A1A  Index  to  last  character  in  the  RS-232  output 

buffer  [669/$029D] 

2587  $0A1B  Index  to  first  character  in  the  RS-232  output 

buffer  [670/$029E] 
2592  $0A20  Maximum  number  of  characters  in  the  key- 

board buffer  [649/$0289] 
2594  $0A22  Enable/disable  key  repeating  (128  =  all  keys 

repeat,  64  =  no  keys  repeat,  0  =  space, 
INST/DEL,  and  cursor  keys  delete) 
[650/$028A] 

Storage  area  for  screen  editor  variables  during 
40/80-column  screen  display  exchanges 
$0AC0  Number  of  function  ROMs  present 

$0AC1-$0AC4    Table  of  function  ROM  identifier  bytes 
$0B00-$0BBF      Cassette  buffer  [828-1019/$33C-$03FB] 
$0B00-$0BFF      Holds  image  of  boot  sector  during  disk  boot 
$0C00-$0CFF     RS-232  input  buffer 
$0D00-$0DFF     RS-232  output  buffer 
$0E00-$0FFF      Sprite  definition  area 
$1000-$  1009       Table  of  indexes  to  function  key  definitions 
$100A-$10FF      Storage  area  for  function  key  definitions 
$1208  Error  number  for  last  error 

$1209-$120A      Line  number  where  last  error  occurred 
$1210-$1211       Pointer  to  end  of  BASIC  program  text  (in 
bank  0) 
4626-4627     $1212-$1214       Pointer  to  top  of  memory  for  BASIC  program 

text  (in  bank  0) 
4632-4634     $1218-$121A      JSR  and  address  for  USR  statement 

2024-65279  ($0800-$FEFF)  Bank  1:  BASIC  Variable  Storage 

7168-65279  ($1C00-$FEFF)  Bank  0:  BASIC  Program  Text  Storage 

7168-16383  ($1C00-$3FFF)  Bank  0:  40-Column  High-Resolution 
Screen  and  Color  Memory  (if  used) 

7168-8191      $1C00-$1FFF    Color  memory  for  bitmapped  screen 
8192-16383    $2000-$3FFF    Bitmap  for  high-resolution  screen 

16348-45055  ($4000-$AFFF)  BASIC  ROM 


2624-2687     $0A40-$0A7F 


2752 

2753- 

2816- 

2816- 

3072- 

3328- 

3584- 

4096- 

4106- 

4616 

4617- 

4624- 


2756 
3007 
3071 
3327 
3583 
4095 
4105 
4351 

4618 
•4625 
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16343      $4000      BASIC  cold-start  vector 
16346     $4003      BASIC  warm-start  vector 
16349     $4006      BASIC  IRQ  entry  vector 

45056-49151  ($B000-$BFFF)  Machine  Language  Monitor  ROM 

45056     $B000     Monitor  cold-start  vector 
45059      $B003     Monitor  BRK  entry  vector 

49152-53247  ($C000-$CFFF)  Screen  Editor  ROM 


U 
U 

u 
u 


Editor 
49152 
49155 
49158 
49161 
49164 
49167 

49170 
49173 
49176 
49179 
49182 
49185 
49188 
49191 

49194 

49197 


Jump  Table 
$C000     Initialize  screen  editor  and  video  chips  (Kernal  CINT) 
$C003     Display  a  character 

$C006     Get  a  key  from  keyboard  buffer  (GETIN  from  keyboard) 
$C009     Get  a  character  from  the  screen  (BASIN  from  screen) 
$C00C    Print  a  character  on  the  screen  (BSOUT  to  screen) 
$C00F     Return  number  of  lines  and  columns  in  current  window 

(Kernal  SCRORG) 
$C012     Scan  keyboard  for  keypress  (Kernal  KEY) 
$C015     Check  for  key  repeat 
$C018     Read  or  set  cursor  position  (Kernal  PLOT) 
$C01B     Move  cursor  on  80-column  screen 
$C01E    Handle  ESC  key  sequences 
$C021     Define  a  programmable  key  (Kernal  PFKEY) 
$C024     Editor  IRQ  entry  vector 
$C027    Initialize  character  set  for  80-column  display  (Kernal 

DLCHR) 
$C02A    Switch  between  40-  and  80-column  displays  (Kernal 

SWAPPER) 
$C02D    Set  window  boundaries 


53248-57343  ($D000-$DFFF)  Character  ROM 

53248-54271    $D000-$D3FF    Uppercase/graphics  set  definitions  (normal) 
54272-55295    $D400-$D7FF    Uppercase/graphics  set  definitions  (reverse 

video) 
55296-56319    $D800-$DBFF    Lowercase/uppercase  set  definitions 

(normal) 
56320-57343    $DC00-$DFFF  Lowercase/uppercase  set  definitions  (reverse 

video) 

53248-57343  ($D000-$DFFF)  I/O  Block 


u 


53248- 
54272- 
54528- 
54784- 
55296- 
56320- 
56576- 


53296  $D000-$D030    VIC  40-column  video  chip 

•54300  $D400-$D41C   SID  sound  chip 

54539  $D500-$D50B    MMU  memory  management  chip 

54785  $D600-$D601    8563  80-column  video  chip 

•56319  $D800-$DBFF    Color  memory  for  40-column  screen 

•56335  $DC00-$DC0F  CIA  input/output  chip  1 

•56591  $DD00-$DD0F  CIA  input/output  chip  2 
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56832-57087    $DE00-$DEFF    Expansion  I/O  slot  (unused) 
57088-57098    $DF00-$DF0A   REC  expansion  memory  controller  chip  in 

memory  expansion  module 

57344-65535  ($E000-$FFFF)  Kernal  ROM 

New  Kernal  Jump  Table  Entries  for  the  128 

65351  $FF47     SPIN_SPOUT  Set  serial  ports  for  fast  input  or  output 
65354  $FF4A     CLOSE_ALL    Close  all  files  to  a  device 
65357  $FF4D     C64MODE        Enter  64  mode 
65360  $FF50     DMA_CALL    Send  command  to  DMA  device 
65363  $FF53      BOOT_CALL   Boot  a  program  from  disk 
65366  $FF56     PHOENIX         Initialize  function  ROM  cartridges 
65369  $FF59     LKUPLA  Look  up  logical  file  number  in  file  tables 

65372  $FF5C     LKUPSA  Look  up  secondary  address  in  file  tables 

65375  $FF5F     SWAPPER         Switch  between  40-  and  80-column  displays 
65378  $FF62      DLCHR  Initialize  character  set  for  80-column  display 

65381   $FF65      PFKEY  Assign  a  string  to  a  function  key 

65384  $FF68      SETBNK  Set  banks  for  I/O  operations 

65387  $FF6B     GETCFG  Get  byte  to  configure  MMU  for  any  bank 

65390  $FF6E     JSRFAR  Jump  to  a  subroutine  in  any  bank,  with  re- 

turn to  the  calling  bank 
65393  $FF71     JMPFAR  Jump  to  a  routine  in  any  bank,  with  no  re- 

turn to  the  calling  bank 
65396  $FF74     INDFET  Load  a  byte  from  an  address  (offset  of  Y)  in 

any  bank 
65399  $FF77     INDSTA  Store  a  byte  to  an  address  (offset  of  Y)  in 

any  bank 
65402  $FF7A    INDCMP  Compare  a  byte  to  the  contents  of  an  ad- 

dress (offset  of  Y)  in  any  bank 
65405  $FF7D    PRIMM  Print  the  string  in  memory  immediately 

following  the  JSR  to  this  routine 

Standard  Commodore  Kernal  Jump  Table 

(Also  found  on  the  Commodore  64,  VIC-20,  16,  and  Plus/4) 

65409  $FF81      CINT  Initialize  screen  editor  and  video  chips 

65412  $FF84     IOINIT        Initialize  I/O  devices 

65415  $FF87     RAMTAS     Initialize  RAM  and  buffers 

65418  $FF8A    RESTOR      Restore  default  values  for  Kernal  indirect  RAM 

vectors 
65421   $FF8D     VECTOR     Set  or  copy  Kernal  indirect  RAM  vectors 
65424  $FF90     SETMSG     Enable  or  disable  Kernal  messages 
65427  $FF93      SECND       Send  secondary  address 
65430  $FF96     TKSA  Send  secondary  address  to  talker 

65433  $FF99      MEMTOP    Set  or  read  top  of  RAM 
65436  $FF9C     MEMBOT    Set  or  read  bottom  of  RAM 
65439  $FF9F     KEY  Read  the  keyboard 

65442  $FFA2     SETTMO     Enable/disable  IEEE  timeouts  (unused  in  the 

128) 
65445  $FFA5     ACPTR        Input  a  byte  from  the  serial  bus 
65448  $FFA8     CIOUT        Output  a  device  to  the  serial  bus 
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Send  untalk  command  to  serial  device 

Send  unlisten  command  to  serial  device 

Send  listen  command  to  serial  device 

Send  talk  command  to  serial  device 

Read  the  I/O  status 

Set  channel,  device  number,  and  secondary 

address 

Specify  length  and  address  of  current  filename 

Open  a  logical  file 

Close  a  logical  file 

Set  a  specified  channel  for  input 

Set  a  specified  channel  for  output 

Clear  all  channels 

Retrieve  a  byte  from  the  input  channel 

Send  a  byte  to  the  output  channel 

Load  or  verify  data  from  device 

Save  contents  of  memory  to  a  device 

Set  jiffy  clock 

Read  jiffy  clock 

Read  RUN/STOP  key  status 

Get  a  byte  from  the  input  buffer 

Close  all  files  and  channels 

Update  jiffy  clock 

Get  size  of  current  screen  window 

Set  or  read  cursor  position 

Get  location  of  I/O  block 

65280-65284  ($FF00-$FF04)  Common  MM U  Registers 


65451   $FFAB 

UNTLK 

65454  $EFAE 

UNLSN 

65457  $FFB1 

LISTN 

65460  $FFB4 

TALK 

65453  $FFB7 

READSS 

65466  $FFBA 

SETLFS 

65469  $FFBD 

SETNAM 

65472  $FFC0 

OPEN 

65475  $FFC3 

CLOSE 

65478  $FFC6 

CHKIN 

65481   $FFC9 

CKOUT 

65484  $FFCC 

CLRCH 

65487  $FFCF 

BASIN 

65490  $FFD2 

BSOUT 

65493  $FFD5 

LOAD 

65496  $FFD8 

SAVE 

65499  $FFDB 

SETTIM 

65502  $FFDE 

RDTIM 

65505  $FFE1 

STOP 

65508  $FFE4 

GETIN 

65511   $FFE7 

CLALL 

65514  $FFEA 

UDTIM 

65517  $FFED 

SCRORG 

65520  $FFF0 

PLOT 

65523  $FFF3 

IOBASE 

u 
u 
u 
u 
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LADS  Source  Code 


1  The  source  code  for  LADS  (Label  Assembly  Development  Sys- 

tem) is  divided  into  13  sections,  each  of  which  accomplishes  a 
("""J  particular  task  for  the  assembler.  All  subroutines  and  most  in- 

1  dividual  instructions  are  commented.  If  you  are  interested  in 

studying  or  customizing  the  assembler,  here  is  a  brief  over- 
view of  functions  of  the  various  sections: 

•  Defs.  All  the  labels  for  zero  page  pointers  and  ROM  routines 
used  by  the  assembler  are  defined  here. 

•  Eval.  The  main  routine.  Most  other  sections  of  the  assembler 
are  called  from  within  Eval  to  perform  their  various  services. 
Eval  starts  assembly  (line  30)  and  ends  assembly  (line  4260). 
In  between,  Eval  takes  each  line  of  source  code  apart, 
determining  the  intended  addressing  mode. 

•  Equate.  Builds  the  database  of  labels  during  the  assembler's 
first  pass  through  the  source  code. 

•  Array.  Searches  through  the  label  database  on  the  second 
pass  and  locates  a  label  name  and  its  numeric  value. 

•  Openl.  Loads  or  saves  disk  files  when  DISKLADS  is  invoked 
with  .D 

•  Findmn.  A  search  routine  to  look  through  the  list  of  8502 
mnemonics  (in  Tables  below)  to  find  the  correct  opcode. 

•  Getsa.  Locates  the  start  address  as  the  first  thing  in  the 
source  code.  Also  contains  the  byte-by-byte  source  code 
reading  routine,  CHARIN. 

•  Valdec.  Transforms  ASCII  numerals  from  the  source  code 
into  integers.  Thus,  the  characters  2  5  become  the  number  25 

f""l  after  Valdec  finishes  with  them. 

•  Indisk.  The  main  input  routine.  Each  line  of  source  code  is 
brought  in,  analyzed  in  various  ways,  and  prepared  for  Eval. 

j""j  •  Math.  Handles  the  +  pseudo-op. 

•  Printops.  Keeps  track  of  our  location  within  the  object  code 
and  formats  screen  and  printer  output  in  various  ways. 

[""]  •  Pseudo.  Handles  all  pseudo-ops  except  +  *=  and  .BYTE. 

The  .D  section  transforms  RAMLADS  into  DISKLADS. 

•  Tables.  LADS's  internal  database.  Contains  lookup  tables  of 
/"I  mnemonics,  opcodes,  and  addressing-mode  categories.  In- 
cludes flags,  pointers,  error  messages,  and  registers  used  by 
various  routines. 
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Library  of  Subroutines 


Here  is  a  collection  of  techniques  you'll  need  to  use  in  many 
of  your  ML  programs.  Those  techniques  which  are  not  inher- 
ently easy  to  understand  are  followed  by  an  explanation. 

Increment  and  Decrement  Double-Byte  Numbers 

You'll  often  want  to  raise  or  lower  a  number  by  1.  To  in- 
crement a  number,  you  add  1  to  it:  Incrementing  5  results  in  6. 
Decrementing  lowers  a  number  by  1.  Single-byte  numbers  are 
easy;  you  just  use  INC  or  DEC.  But  you'll  often  want  to  in- 
crement two-byte  numbers  which  hold  addresses,  game 
scores,  pointers,  or  some  other  number  which  requires  two 
bytes.  Two  bytes,  ganged  together  and  seen  as  a  single  num- 
ber, can  hold  values  from  0  ($0000)  up  to  65535  ($FFFF). 
Here's  how  to  raise  a  two-byte  number  by  1,  to  increment  it: 
(Let's  assume  that  the  number  you  want  to  increment  or 
decrement  is  located  in  addresses  $0605  and  $0606,  and  the 
ML  program  segment  performing  the  action  is  located  at 
$5000.) 

5000  INCREMENT  INC  $0605  Raise  the  low  byte. 

5003  BNE  GOFORTH  If  not  zero,  leave  high  byte  alone. 

5005  INC  $0606  Raise  high  byte. 

5008  GOFORTH...  Continue  with  program. 

The  trick  in  this  routine  is  the  BNE.  If  the  low  byte  isn't 
raised  to  0  (from  255),  we  don't  need  to  add  a  carry  to  the 
high  byte,  so  we  jump  over  it.  However,  if  the  low  byte  does 
turn  into  a  0,  the  high  byte  must  then  be  raised.  This  is  similar 
to  the  way  an  ordinary  decimal  increment  creates  a  carry 
when  you  add  1  to  9  (or  to  99  or  999).  The  lower  number 
turns  to  0,  and  the  next  column  over  is  raised  by  1. 

To  double-decrement,  you  need  an  extra  step.  The  reason 
it's  more  complicated  is  that  the  8502  chip  has  no  way  to  test 
if  you've  crossed  over  to  $FF,  down  from  $00.  BNE  and  BEQ 
will  test  if  something  is  0,  but  nothing  tests  for  $FF.  (The  N 
flag  is  turned  on  when  you  go  from  $00  to  $FF,  and  BPL  or 
BMI  could  test  it.)  The  problem  with  it,  though,  is  that  the  N 
flag  isn't  limited  to  sensing  $FF.  It  is  sensitive  to  any  number 
higher  than  127  decimal  ($7F). 

343 


Appendix  E 


So,  here's  the  way  to  handle  double-deckers: 

5000  LDA  $0605  Load  in  the  low  byte,  affecting  the 

zero  flag. 
5003  BNE  FIXLOWBYTE  If  it's  not  zero,  lower  it,  skipping 

high  byte. 
5005  DEC  $0606  Zero  in  low  byte  forces  this. 

5008  FIXLOWBYTE  DEC  $0605    Always  dec  the  low  byte. 

Here  we  always  lower  the  low  byte,  but  lower  the  high 
byte  only  when  the  low  byte  is  found  to  be  zero.  If  you  think 
about  it,  that's  the  way  any  subtraction  would  work. 


U 
U 

u 
u 
u 


Comparison 

Comparing  a  single-byte  against  another  single-byte  is  easily 
achieved  with  CMP.  Double-byte  comparison  can  be  handled 
this  way: 

(Assume  that  the  numbers  you  want  to  compare  are  lo- 
cated in  addresses  $0605,0606  and  $0700,0701.  The  ML  pro- 
gram segment  performing  the  comparison  is  located  at  $5000.) 

5000  SEC 

5001  LDA  $0605     Low  byte  of  first  number 
5004    SBC    $0700     Low  byte  of  second  number 

5007  STA    $0800  Temporary  holding  place  for  this  result 

500A  LDA   $0606  High  byte  of  first  number 

500D  SBC    $0701  High  byte  of  second  number,  leave  result  in  A 

5010  ORA  $0800  Results  in  zero  if  A  and  $0800  were  both  zero 

The  flags  in  the  status  register  are  left  in  various  states 
after  this  routine — you  can  test  them  with  the  B  instructions 
and  branch  according  to  the  results.  The  ORA  sets  the  Z  (zero) 
flag  if  the  results  of  the  first  subtraction  (left  in  $0800)  and  the 
second  subtraction  (in  A,  the  accumulator)  were  both  zero. 

This  would  happen  only  if  the  two  numbers  tested  were  | I 

identical,  and  BEQ  would  test  for  this  (Branch  if  EQual). 

If  the  first  number  is  lower  than  the  second,  the  carry  flag 

would  have  been  cleared,  so  BCC  (Branch  if  Carry  Clear)  will  j | 

test  for  that  possibility.  If  the  first  number  is  higher  than  the 
second,  BCS  (Branch  if  Carry  Set)  will  be  true.  You  can  there- 
fore branch  with  BEQ  for  =,  BCC  for  <,  and  BCS  for  >.  Just  [_J 
keep  in  mind  which  number  you're  considering  the  first  and 
which  the  second  in  this  test. 
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pj  Double-Byte  Addition 

CLC  ADC  and  SEC  SBC  will  add  and  subtract  one-byte  num- 
bers. To  add  two-byte  numbers,  use: 
P"]  (Assume  that  the  numbers  you  want  to  add  are  located  in 

~  addresses  $0605,0606  and  $0700,0701.  The  ML  program  seg- 

ment performing  the  addition  is  located  at  $5000.) 
^^■^ 

!     1  5000  CLC  Always  do  this  before  any  addition. 

5001  LDA  $0605 

5004  ADC  $0700 

5007  STA  $0605    The  result  will  be  left  in  $0605,0606. 

500A  LDA  $0606 

500D  ADC  $0701 

5010  STA  $0606 

It's  not  necessary  to  put  the  result  on  top  of  the  number 
in  $0605,0606 — you  can  put  it  anywhere.  But  you'll  often  be 
adding  a  particular  value  to  another  and  not  needing  the  orig- 
inal any  longer — adding  ten  points  to  a  score  for  every  blasted 
alien  is  an  example.  If  this  were  the  case,  following  the  logic 
of  the  routine  above,  you  would  have  a  10  in  $0701,0702: 

0701  0A  The  ten  points  you  get  for  hitting  an  alien 

0702  00 

You'd  want  that  10  to  remain  undisturbed  throughout  the 
game.  The  score,  however,  keeps  changing  during  the  game 
and,  held  in  $0605,0606,  it  can  be  covered  over,  replaced  with 
each  addition. 

Double-Byte  Subtraction 

This  is  quite  similar  to  double-byte  addition.  Since  subtracting 
one  number  from  another  is  also  a  comparison  of  those  two 

j    ;  numbers,  you  could  combine  subtraction  with  the  double-byte 

comparison  routine  above  (using  ORA).  In  any  event,  this  is 
the  way  to  subtract  double-byte  numbers.  Be  sure  to  keep 

f""j  straight  which  number  is  being  subtracted  from  the  other. 

We'll  call  the  number  being  subtracted  the  second  number. 

(Assume  that  the  number  you  want  to  subtract — the  "sec- 

pi  ond  number" — is  located  in  addresses  $0700,0701,  and  that 

the  number  it  is  being  subtracted  from — the  "first  number" — 
is  held  in  $0605,0606.  The  result  will  be  left  in  $0605,0606. 

j""~!  The  ML  program  segment  performing  the  subtraction  is  lo- 

cated at  $5000.) 
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5000    SEC 

Always  do  this  before  any  subtraction 

Li 

5001     LDA   $0605 

Low  byte  of  first  number 

5004    SBC    $0700 

Low  byte  of  second  number 

5007    STA    $0605 

Result  will  be  left  in  $0605,0606 

U 

500A  LDA   $0606 

High  byte  of  first  number 

500D   SBC    $0701 

High  byte  of  second  number 

5010    STA    $0606 

High  byte  of  final  result 

U 

Multibyte  Addition  and  Subtraction 

Using  the  methods  for  adding  and  subtracting  illustrated  above, 
you  can  manipulate  larger  numbers  than  can  be  held  within 
two  bytes  (65535  is  the  largest  possible  two-byte  integer). 
Here's  how  to  subtract  one  four-byte-long  number  from  another. 
The  locations  and  conditions  are  the  same  as  for  the  two-byte 
subtraction  example  above,  except  the  "first  number"  (the 
minuend)  is  held  in  the  four-byte  chain,  $0605,0606,0607,0608, 
and  the  "second  number"  (the  subtrahend,  the  number  being 
subtracted  from  the  first  number)  is  in  $0700,0701,0702,0703. 

Also  observe  that  the  most  significant  byte  is  held  in 
$0703  and  $0608.  We'll  use  the  Y  register  for  indirect  Y 
addressing,  four  bytes  in  zero  page  as  pointers  to  the  two 
numbers,  and  the  X  register  as  a  counter  to  make  sure  that  all 
four  bytes  are  dealt  with.  This  means  that  X  must  be  loaded 
with  the  length  of  the  chains  we're  subtracting — in  this  case,  4. 

Length  of  the  byte  chains. 

Set  Y... 

always  before  subtraction. 


5000 

LDX    #4 

5002 

LDY    #0 

5004 

SEC 

5005 

LOOP  LDA  (FIRST), Y 

5007 

SBC    (SECONDLY 

5009 

STA    (FIRSTLY 

500B 

INY 

500C 

DEX 

5010 

BNE    LOOP 

The  answer  will  be  left  in  $0605-$0608. 

Raise  index  to  chains.  \     f 

Lower  counter.  ' — ' 
Haven't  yet  done  all  four  bytes. 

Before  this  will  work,  the  pointers  in  zero  page  must  have  j    j 

been  set  up  to  allow  the  indirect  Y  addressing.  This  is  one  way 
to  do  it: 

2000  FIRST  =  $FB  Define  zero  page  pointers  at  $FB  and  $FD. 

2000  SECOND  =  $FD 

2000  SETUP  LDA  #5      Set  up  pointer  to  $0605. 

2002  STA    FIRST 

2004  LDA    #6 

2006  STA    FIRST +1 


\    i 
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2008  LDA  #0  Set  up  pointer  to  $0700. 

200A  STA  SECOND 

200C  LDA  #7 

200E  STA  SECOND +1 

Multiplication 

X  2 

ASL  (no  argument  used,  "accumulator  addressing  mode")  will 
multiply  the  number  in  the  accumulator  by  2. 

X3 

To  multiply  by  3,  use  a  temporary  variable  byte  we'll  call 
TEMP. 

5000    STA    TEMP  Put  the  number  into  the  variable. 

5003  ASL  Multiply  it  by  2. 

5004  ADC  TEMP  (X  *  2  +  X  =  X  *  3)— the  answer  is  in  A. 

X4 

To  multiply  by  4,  just  ASL  twice. 

5000  ASL    *  2 

5001  ASL    *  2  again 

X  4  (Two  Byte) 

To  multiply  a  two-byte  integer  by  4,  use  a  two-byte  variable 
we'll  call  TEMP  and  TEMP+1. 

5000  ASL  TEMP  Multiply  the  low  byte  by  2... 

5003  ROL  TEMP+1  moving  any  carry  into  the  high  byte. 

5006  ASL  TEMP  Multiply  the  low  byte  by  2  again. 

5009  ROL  TEMP+1  Again  acknowledge  any  carry. 

X  10 

To  multiply  a  two-byte  integer  by  10,  use  an  additional  two- 
byte  variable  we'll  call  STORE. 

5000  First,  put  the  number  into  STORE  for 

safekeeping. 

5000  LDA  TEMP:STA  STORE:LDA  TEMP+1:STA  STORE+1 

500C  Then  multiply  it  by  4. 

500C  ASL  TEMP         Multiply  the  low  byte  by  2... 

500F  ROL  TEMP+1    moving  any  carry  into  the  high  byte. 

5012  ASL  TEMP         Multiply  the  low  byte  by  2  again. 

5015  ROL  TEMP+1;  Again  acknowledge  any  carry. 

5018  Then  add  the  original,  resulting  in  X  *  5. 
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5018 

LDA 

STORE 

501B 

ADC 

TEMP 

501E 

STA 

TEMP 

5021 

LDA 

STORE +1 

501D 

ADC 

TEMP+1 

5024 

STA 

TEMP+1 

5027 

5027 

ASL 

TEMP 

502A 

ROL 

TEMP+1 

Then  just  multiply  by  2  since  (5*2  =  10) 


u 
u 
u 
u 
u 


X  ? 

To  multiply  a  two-byte  integer  by  other  odd  values,  just  use  a 
similar  combination  of  addition  and  multiplication  which  re- 
sults in  the  correct  amount  of  multiplication. 

X  100 

To  multiply  a  two-byte  integer  by  100,  just  go  through  the 
above  subroutine  twice. 

X  256 

To  multiply  a  one-byte  integer  by  256,  just  transform  it  into  a 
two-byte  integer. 

5000  LDA   TEMP 

5003  STA    TEMP+1 

5006  LDA   #0 

5008  STA    TEMP 

Division 

-5-  2 

LSR  (no  argument  used,  "accumulator  addressing  mode")  will 

divide  the  number  in  the  accumulator  by  2.  \ j 

To  divide  by  4,  just  LSR  twice.  [_j 

5000  LSR    /2 

5001  LSR     /  2  again 


■*-  4  (Two  Byte) 

To  divide  a  two-byte  integer,  called  TEMP,  by  2: 

5000  LSR    TEMP+1    Shift  high  byte  right... 

5001  ROR  TEMP         pulling  any  carry  into  the  low  byte. 


\    \ 
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Typing  In  LADS 


LADS  is  a  very  long  program.  The  directions  for  typing  it  in 
r-_,  are  listed  below.  For  those  who  prefer  not  to  type  it  in,  it  can 

i    i  be  purchased  on  disk,  along  with  many  of  the  other  programs 

in  this  book,  by  calling  COMPUTE!  Publications  toll-free  at  1- 
800-346-6767  (in  New  York,  call  1-212-887-8525)  or  by  using 
the  coupon  in  the  back  of  this  book.  Be  sure  to  state  that  you 
want  the  disk  for  the  book  128  Machine  Language  for  Beginners. 

In  order  to  make  it  as  easy  as  possible  to  type  in  LADS, 
we've  included  two  program  entry  aids  written  in  BASIC: 
"The  Automatic  Proofreader"  and  "MLX."  To  assist  you  in 
understanding  how  to  enter  these  programs,  COMPUTE!  has 
established  the  following  listing  conventions. 

Generally,  BASIC  program  listings  like  the  one  for  MLX 
will  contain  words  within  braces  which  spell  out  any  special 
characters:  {DOWN}  means  to  press  the  cursor-down  key;  {5 
SPACES}  means  to  press  the  space  bar  five  times. 

To  indicate  that  a  key  should  be  shifted  (press  the  key 
while  holding  down  the  SHIFT  key),  the  key  will  be  under- 
lined in  our  listings.  For  example,  S  means  to  type  the  S  key 
while  holding  the  SHIFT  key.  This  would  appear  on  your 
screen  as  a  heart  symbol.  If  you  find  an  underlined  key  en- 
closed in  braces  (for  example,  {10  N}),  you  should  type  the 
key  as  many  times  as  indicated.  In  that  case,  you  would  enter 
ten  shifted  N's. 

If  a  key  is  enclosed  in  special  brackets,  \<  >\,  you  should 

i    i  hold  down  the  Commodore  key  while  pressing  the  key  inside 

the  special  brackets.  (The  Commodore  key  is  the  key  in  the 
lower  left  corner  of  the  keyboard.)  Again,  if  the  key  is  pre- 

/    j  ceded  by  a  number,  you  should  press  the  key  as  many  times 

as  indicated;  f<9(g)>|  means  type  Commodore-@  nine  times. 
.  Refer  to  Figure  F-l  when  entering  cursor  and  color  control 

i    |  keys: 
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Figure  F-l.  Keyboard  Conventions 
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Typing  In  LADS 

Before  you  can  enter  LADS,  you  must  first  enter  the  "Machine 
Language  Editor"  program  (MLX),  Program  F-2.  MLX  will 
allow  you  to  enter  the  LADS  object  code  without  a  mistake.  It 
is  therefore  extremely  important  that  MLX  be  entered  cor- 
rectly. To  assist  you  in  typing  in  MLX  you  should  use  "The 
Automatic  Proofreader."  Here  are  the  steps  you  should  follow 
to  enter  LADS. 

1.  Read  the  directions  for  using  the  Automatic  Proofreader 
below. 

2.  Type  in  Program  F-l,  the  Automatic  Proofreader,  and  save 
it  to  disk  or  tape. 

3.  Activate  the  Automatic  Proofreader  and  type  in  and  save 
Program  F-2,  MLX,  checking  each  line  with  the  Automatic 
Proofreader  as  you  finish  typing  it  in. 
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t    \  4.  Read  the  directions  for  using  MIX 

5.  Run  MLX  and  begin  entering  the  object  code  for  LADS, 
Program  F-3. 

jl  6.  When  you  have  finished  entering  the  LADS  object  code, 

use  the  Save  option  of  MLX  to  save  a  copy. 
7.  You  are  now  ready  to  BLOAD  LADS. 

;    ;  8.  Type  in  and  save  Program  F-4,  using  the  filename  LOADER. 

If  you  have  a  1571  disk  drive,  use  the  "Autoboot  Maker" 
utility  from  the  Test/Demo  Disk  that  came  with  the  1571 
drive  to  make  "Loader"  run  when  you  turn  on  your  system. 


The  Automatic  Proofreader 

Philip  I.  Nelson 

"The  Automatic  Proofreader"  helps  you  type  in  program  list- 
ings without  typing  mistakes.  It's  a  short  error-checking  pro- 
gram that  conceals  itself  in  memory  and  adheres  to  your 
Commodore's  operating  system.  Each  time  you  press  RETURN 
to  enter  a  program  line,  the  Proofreader  displays  a  two-letter 
checksum  in  reverse  video  at  the  top  of  your  screen.  If  the 
checksum  on  your  screen  doesn't  match  the  one  in  the  printed 
listing,  you've  typed  the  line  incorrectly — it's  that  simple.  You 
don't  have  to  use  the  Proofreader  to  enter  printed  listings,  but 
doing  so  greatly  reduces  your  chances  of  making  a  typo. 

Getting  Started 

First,  type  in  the  Automatic  Proofreader  program  exactly  as  it 
appears  in  the  listing.  Since  the  Proofreader  can't  check  itself, 
type  carefully  to  avoid  mistakes.  Don't  omit  any  lines,  even  if 
they  contain  unfamiliar  commands  or  you  think  they  don't  ap- 
ply to  your  computer.  As  soon  as  you're  finished  typing  the 
Proofreader,  save  at  least  two  copies  on  disk  or  tape  before 
running  it  the  first  time.  This  is  very  important  because  the 
Proofreader  erases  the  BASIC  portion  of  itself  when  you  run 
it,  leaving  only  the  machine  language  portion  in  memory. 

When  that's  done,  type  RUN  and  press  RETURN.  After 
announcing  which  computer  it's  running  on,  the  Proofreader 
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installs  the  ML  routine  in  memory,  displays  the  message  ]    ' 

PROOFREADER  ACTIVE,  erases  the  BASIC  portion  of  itself, 

and  ends.  If  you  type  LIST  and  press  RETURN,  you'll  see  that 

no  BASIC  program  remains  in  memory.  The  computer  is  ready  1    i 

for  you  to  type  in  a  new  BASIC  program. 

Entering  Programs  1    i 

Once  the  Proofreader  is  active,  you  can  begin  typing  in  a 
BASIC  program  as  usual.  Every  time  you  finish  typing  a  line 
and  press  RETURN,  the  Proofreader  displays  a  two-letter 
checksum  (reverse-video  letters)  in  the  upper  left  corner  of  the 
screen.  Compare  this  checksum  with  the  two-letter  checksum 
printed  to  the  left  of  the  corresponding  line  in  the  program 
listing.  If  the  letters  match,  it's  almost  certain  the  line  was 
typed  correctly.  If  the  letters  don't  match,  check  for  your  mis- 
take and  correct  the  line. 

The  Proofreader  ignores  spaces  that  aren't  enclosed  in 
quotation  marks,  so  you  can  omit  spaces  (or  add  extra  ones) 
between  keywords  and  still  see  a  matching  checksum.  For  ex- 
ample, these  two  lines  generate  the  same  checksum: 

10  PRINT'THIS  IS  BASIC" 

10  PRINT  "THIS  IS  BASIC" 

However,  since  spaces  inside  quotation  marks  are  almost 
always  significant,  the  Proofreader  pays  attention  to  them.  For 
instance,  these  two  lines  generate  different  checksums: 

10  PRINT"THIS  IS  BASIC" 
10  PRINT"THIS  ISBA        SIC" 

A  common  typing  mistake  is  transposition — typing  two 
successive  characters  in  the  wrong  order,  like  PIRNT  instead 
of  PRINT  or  64378  instead  of  64738.  A  checksum  program  s    ( 

that  adds  up  the  values  of  all  the  characters  in  a  line  can't  L*— J 

possibly  detect  transposition  errors  (it  can  only  tell  whether 
the  right  characters  are  present,  regardless  of  what  order  I    [ 

they're  in).  Because  the  Proofreader  computes  the  checksum  ' — ' 

with  a  more  sophisticated  formula,  it  is  also  sensitive  to  the 
position  of  each  character  within  the  line  and  thus  catches  i    f 

transposition  errors.  L--J 

The  Proofreader  does  not  accept  keyword  abbreviations 
(for  example,  ?  instead  of  PRINT).  If  you  prefer  to  use  abbrevi- 
ations, you  can  still  check  the  line  with  the  Proofreader:  Sim- 
ply LIST  the  line  after  typing  it,  move  the  cursor  back  onto 
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i    I  the  line,  and  press  RETURN.  LISTing  the  line  substitutes  the 

full  keyword  for  the  abbreviation  and  allows  the  Proofreader 
to  work  properly.  The  same  technique  works  for  rechecking  a 
program  you've  already  typed  in:  Reload  the  program,  LIST 
several  lines  on  the  screen,  and  press  RETURN  over  them. 
.  Do  not  use  any  GRAPHIC  commands  while  the  Proofreader 

■    |  is  active.  When  you  activate  a  command  like  GRAPHIC  1,  the 

computer  moves  everything  at  the  start  of  BASIC  program 
space — including  the  Proofreader — to  another  memory  area, 
causing  the  Proofreader  to  crash.  The  same  thing  happens  if 
you  run  any  program  that  contains  a  GRAPHIC  command. 
The  Proofreader  deallocates  any  graphics  areas  before  install- 
ing itself  in  memory,  but  you  are  responsible  for  seeing  that 
the  computer  remains  in  this  configuration. 

Though  the  Proofreader  doesn't  interfere  with  other 
BASIC  operations,  it's  always  a  good  idea  to  disable  it  before 
running  any  other  program.  Some  programs  may  need  the 
space  occupied  by  the  Proofreader's  ML  routine  or  may  create 
other  memory  conflicts.  However,  the  Proofreader  is  purposely 
made  difficult  to  dislodge:  It's  not  affected  by  tape  or  disk  op- 
erations, or  by  pressing  RUN/STOP-RESTORE.  The  simplest 
way  to  disable  it  is  to  turn  the  computer  off,  then  on  again. 


Machine  Language  Editor,  MLX 

Ottis  R.  Cowper 

"MLX"  is  a  new  way  to  enter  long  machine  language  pro- 
grams without  a  lot  of  fuss.  MLX  lets  you  enter  the  numbers 
from  a  special  list  that  looks  similar  to  BASIC  DATA  state- 
ments. It  checks  your  typing  on  a  line-by-line  basis.  It  won't 
let  you  enter  invalid  characters  or  let  you  continue  if  there's  a 
mistake  in  a  line.  It  won't  even  let  you  enter  a  line  or  digit  out 
of  sequence. 

Using  MLX 

Type  in  and  save  some  copies  of  MLX  (you'll  want  to  use  it  to 
enter  future  ML  programs  from  other  COMPUTE!  publica- 
tions). When  you're  ready  to  enter  "LADS  Object  Code,"  Pro- 
gram F-3,  load  and  run  MLX.  It  asks  you  for  a  starting  address 
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and  an  ending  address.  These  addresses  are  J    I 

Starting  Address:  2710 
Ending  Address:  3D27 

If  you're  unfamiliar  with  machine  language,  the  addresses  1 ! 

(and  all  other  values  you  enter  in  MLX)  may  appear  strange. 

Instead  of  the  usual  decimal  numbers  you're  accustomed  to,  , 

these  numbers  are  in  hexadecimal — a  base  16  numbering  sys-  1 ' 

tern  commonly  used  by  ML  programmers.  Hexadecimal — hex 
for  short — includes  the  numbers  0-9  and  the  letters  A-F.  But 
don't  worry — even  if  you  know  nothing  about  ML  or  hex,  you 
should  have  no  trouble  using  MLX. 

After  you  enter  the  starting  and  ending  addresses,  MLX 
will  offer  you  the  option  of  clearing  the  workspace.  Choose 
this  option  if  you're  starting  to  enter  LADS  for  the  first  time.  If 
you're  continuing  to  enter  LADS  that  you  partially  typed  from 
a  previous  session,  don't  choose  this  option. 

It's  not  necessary  to  know  more  about  this  option  to  use 
MLX,  but  here's  an  explanation  if  you're  interested:  When  you 
first  run  MLX,  the  workspace  area  contains  random  values. 
Clearing  the  workspace  fills  it  with  zeros.  This  makes  it  easier 
to  find  where  you  left  off  if  you  enter  the  listing  in  multiple 
sittings.  However,  clearing  the  workspace  is  useful  only  before 
you  first  begin  entering  a  listing;  there's  no  need  to  clear  it 
before  you  reload  to  continue  entering  a  partially  typed  listing. 

When  you  save  your  work  with  MLX,  it  stores  the  entire 
contents  of  the  data  buffer.  If  you  clear  the  workspace  before 
starting,  the  incomplete  portion  of  the  listing  is  filled  with  ze- 
ros when  saved  and  thus  refilled  with  zeros  when  reloaded.  If 
you  don't  clear  the  workspace  when  first  starting,  the  in- 
complete portion  of  the  listing  is  filled  with  random  data. 
Whether  or  not  you  clear  the  workspace  before  you  reload,  ]^J 

this  random  data  will  refill  the  unfinished  part  of  the  listing 
when  you  load  your  previous  work.  The  rule,  then,  is  to  use  . 

the  clear  workspace  feature  before  you  begin  entering  data  i_J 

from  a  listing  and  not  to  bother  with  it  afterward. 

At  this  point,  MLX  presents  a  menu  of  commands: 

Enter  data  UJ 

Display  data 

Load  data  (     , 

Save  file  1 ) 

Catalog  disk 
Quit 
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T~]  Entering  a  Listing 

To  begin  entering  data,  press  E.  You'll  be  asked  for  the  address 
at  which  you  wish  to  begin  entering  data.  (If  you  pressed  E  by 

|    |  mistake,  you  can  return  to  the  command  menu  by  pressing 

RETURN.)  When  you  begin  typing  LADS,  you  should  enter 
the  starting  address  here.  If  you're  typing  LADS  in  multiple 

;    |  sittings,  you  should  enter  the  address  where  you  left  off  typing 

at  the  end  of  the  previous  session.  In  any  case,  make  sure  the 
address  you  enter  corresponds  to  the  address  of  a  line  of  the 
LADS  MLX  listing.  Otherwise,  you'll  be  unable  to  enter  the 
data  correctly. 

After  you  enter  the  address,  you'll  see  that  address  appear 
as  a  prompt  with  a  nonblinking  cursor.  Now  you're  ready  to 
enter  data.  Type  in  all  nine  numbers  on  that  line,  beginning 
with  the  first  two-digit  number  after  the  colon  (:).  Each  line 
represents  eight  data  bytes  and  a  checksum.  Although  an 
MLX-format  listing  appears  similar  to  the  "hex  dump"  ma- 
chine language  listings  you  may  be  accustomed  to,  the  extra 
checksum  number  on  the  end  allows  MLX  to  check  your  typ- 
ing. (You  can  enter  the  data  from  an  MLX  listing  using  the 
built-in  monitor  if  the  rightmost  column  of  data  is  omitted,  but 
we  recommend  against  it.  It's  much  easier  to  let  MLX  do  the 
proofreading  and  error  checking  for  you.) 

Only  the  numbers  0-9  and  the  letters  A-F  can  be  typed 
in.  If  you  press  any  other  key  (with  some  exceptions  noted 
below),  you'll  hear  a  warning  buzz.  To  simplify  typing,  MLX 
redefines  the  function  keys  and  the  +  and  —  keys  on  the  nu- 
meric keypad  so  that  you  can  enter  data  one-handed.  Figure  F- 
2  shows  the  keypad  configuration  supported  by  MLX. 

n  MLX  checks  for  transposed  characters.  If  you're  supposed 

i    f  to  type  in  A0  and  instead  enter  0A,  MLX  will  catch  your  mis- 

take. To  correct  typing  mistakes  before  finishing  a  line,  use  the 

__,  INST/DEL  key  to  delete  the  character  to  the  left  of  the  cursor. 

.    I  (The  cursor-left  key  also  deletes.)  If  you  mess  up  a  line  really 

badly,  press  CLR/HOME  to  start  the  line  over. 

_,  The  RETURN  key  is  also  active,  but  only  before  any  data 

1    J  is  typed  on  a  line.  Pressing  RETURN  at  this  point  retuins  you 

to  the  command  menu.  After  you  type  a  character  of  data, 
MLX  disables  RETURN  until  the  cursor  returns  to  the  start  of 

j    1  a  line.  Remember,  you  can  press  CLR/HOME  to  get  to  a  line 

number  prompt  quickly. 


!       I 
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Figure  F-2.  Keypad  for  128  MLX 
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Beep  Or  Buzz 

When  you  enter  a  line,  MLX  recalculates  the  checksum  from 
the  eight  bytes  and  the  address  and  compares  this  value  to  the 
number  from  the  ninth  column.  If  the  values  match,  you'll 
hear  a  pleasant  beep  to  indicate  that  the  line  was  entered  cor- 
rectly. The  data  is  then  added  to  the  workspace  area,  and  the 
prompt  for  the  next  line  of  data  appears.  But  if  MLX  detects  a 
typing  error,  you'll  hear  a  low  buzz  and  see  an  error  message. 
MLX  will  then  redisplay  the  line  for  editing. 

To  make  corrections  in  a  line  that  MLX  has  redisplayed 
for  editing,  compare  the  line  on  the  screen  with  the  one 
printed  in  the  listing,  then  move  the  cursor  to  the  mistake  and 
type  the  correct  key.  The  cursor-left  and  -right  keys  provide 
the  normal  cursor  controls.  (The  INST/DEL  key  now  works  as 
an  alternative  cursor-left  key.)  You  cannot  move  left  beyond 
the  first  character  in  the  line.  If  you  try  to  move  beyond  the 
rightmost  character,  you'll  reenter  the  line.  During  editing,  RE- 
TURN is  active;  pressing  it  tells  MLX  to  recheck  the  line.  You 
can  press  the  CLR/HOME  key  to  clear  the  entire  line  if  you 
want  to  start  from  scratch,  or  if  you  want  to  get  to  a  line  num- 
ber prompt  to  use  RETURN  to  get  back  to  the  menu. 
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I    1  After  you  have  entered  the  last  number  on  the  last  line  of 

the  listing,  MLX  automatically  moves  to  the  Save  option. 

P|  Other  MLX  Functions 

The  second  menu  choice,  DISPLAY  DATA,  examines  memory 
and  shows  the  contents  in  the  same  format  as  the  program 

I    |  listing  (including  the  checksum).  When  you  press  D,  MLX  asks 

you  for  a  starting  address.  Be  sure  that  the  starting  address 
you  give  corresponds  to  a  line  number  in  the  listing.  Other- 
wise, the  display  will  be  meaningless.  MLX  displays  program 
lines  until  it  reaches  the  end  of  the  program,  at  which  point 
the  menu  is  redisplayed.  You  can  pause  the  scrolling  display 
by  pressing  the  space  bar.  (MLX  finishes  printing  the  current 
line  before  halting.)  To  resume  scrolling,  press  the  space  bar 
again.  To  break  out  of  the  display  and  return  to  the  menu 
before  the  ending  address  is  reached,  press  RETURN. 

Two  more  menu  selections  let  you  save  programs  and 
load  them  back  into  the  computer.  These  are  SAVE  FILE  and 
LOAD  FILE;  their  operation  is  quite  straightforward.  When  you 
press  S  or  L,  MLX  asks  you  for  the  filename.  (Again,  pressing 
RETURN  at  this  prompt  without  entering  anything  returns  you 
to  the  command  menu.)  Next,  MLX  asks  you  to  press  either  D 
or  T  to  select  disk  or  tape. 

You'll  notice  the  disk  drive  starting  and  stopping  several 
times  during  a  save.  Don't  panic;  this  is  normal  behavior.  MLX 
opens  and  writes  to  the  file  instead  of  using  the  usual  SAVE 
command.  (Loads,  on  the  other  hand,  operate  at  normal 
speed— thanks  to  the  relocating  feature  of  BASIC  7.0's  BLOAD 
command.)  Remember  that  MLX  saves  the  entire  workspace 
area  from  the  starting  address  to  the  ending  address,  so  the 

jj  save  or  load  may  take  longer  than  you  might  expect  if  you've 

entered  only  a  small  amount  of  data  from  a  long  listing.  When 
saving  a  partially  completed  listing,  make  sure  to  note  the  ad- 

(~~j  dress  where  you  stopped  typing  so  that  you'll  know  where  to 

resume  entry  when  you  reload. 

Error  Alert 

MLX  reports  any  errors  detected  during  the  save  or  load  and 
displays  the  standard  error  messages.  (Tape  users  should  bear 
in  mind  that  the  Commodore  128  is  never  able  to  detect  errors 
when  saving  to  tape.)  MLX  also  has  three  special  load  error 
messages: 
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•  INCORRECT  STARTING  ADDRESS,  which  means  the  file  [J 
you're  trying  to  load  does  not  have  the  starting  address  you 
specified  when  you  ran  MLX.  In  this  case,  no  data  will  be 
loaded. 

•  LOAD  ENDED  AT  address,  which  means  the  file  you're  try- 
ing to  load  ends  before  the  ending  address  you  specified 

when  you  started  MLX.  The  data  from  the  file  is  loaded,  but  j    } 

it  ends  at  the  address  specified  in  the  error  message. 

•  TRUNCATED  AT  ENDING  ADDRESS,  which  means  the  file 
you're  trying  to  load  extends  beyond  the  ending  address  you 
specified  when  you  started  MLX.  The  data  from  the  file  is 
loaded,  but  only  up  to  the  specified  ending  address. 

If  you  see  one  of  these  messages  and  feel  certain  that 
you've  loaded  the  right  file,  exit  and  rerun  MLX,  being  careful 
to  enter  the  correct  starting  and  ending  addresses. 

If  you  wish  to  check  which  programs  are  on  a  disk,  select 
the  C  option  from  the  command  menu  for  a  directory.  You  can 
use  the  128's  NO  SCROLL  key  to  pause  the  display.  After- 
wards, press  any  key  to  return  to  the  menu. 

The  Quit  menu  option  has  the  obvious  effect — it  stops 
MLX  and  enters  BASIC.  The  RUN/STOP  key  is  trapped,  so 
the  Q  option  lets  you  exit  the  program  without  turning  off  the 
computer.  (Of  course,  RUN/STOP-RESTORE  also  gets  you 
out.)  You'll  be  asked  for  verification;  press  Y  to  exit  to  BASIC 
or  any  other  key  to  return  to  the  menu.  After  quitting,  you  can 
type  RUN  again  and  reenter  MLX  without  losing  your  data  as 
long  as  you  don't  use  the  clear  workspace  option. 

The  Finished  Product 

When  you've  finished  typing  all  the  data  for  an  ML  program 

and  saved  your  work,  you're  ready  to  see  the  results.  The  I] 

instructions  for  loading  and  using  the  finished  product  vary 

from  program  to  program.  LADS  should  be  loaded  using  the 

command  BLOAD"LADS"  or  LOAD"LADS",8,l  for  disk  (if  jj 

you  have  a  1571  disk  drive,  BOOT  "LADS"  also  works)  or 

LOAD"LADS",l/l  for  tape  (assuming  you  used  the  filename 

LADS  to  save  the  object  code  through  MLX).  When  you  wish  !    ! 

to  assemble  source  code  once  LADS  is  in  memory,  just  SYS  ~'^ 

10000  (it's  best  to  reload  LADS  after  you  have  loaded  the 

source  code).  I    i 
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P]  An  Ounce  of  Prevention 

By  the  time  you  finish  typing  in  the  data  for  a  long  ML  pro- 
-  gram  such  as  LADS,  you'll  have  many  hours  invested  in  the 

|j  project.  Don't  take  chances — use  our  Automatic  Proofreader  to 

type  MLX,  and  then  test  your  copy  thoroughly  before  first 
using  it  to  enter  any  significant  amount  of  data.  Make  sure  all 

jj  the  menu  options  work  as  they  should.  Enter  fragments  of  the 

program  starting  at  several  different  addresses,  then  use  the 
Display  option  to  verify  that  the  data  has  been  entered  cor- 
rectly. And  be  sure  to  test  the  Save  and  Load  options  several 
times  to  insure  that  you  can  recall  your  work  from  disk  or 
tape.  Don't  let  a  simple  typing  error  in  MLX  cost  you  several 
nights  of  hard  work. 

The  Loader 

This  is  a  suggestion  for  a  LADS  "Loader"  program  (Program 
F-4)  which  will  boot  LADS  if  you  install  it  on  a  disk  and  use 
the  "Autoboot  Maker"  on  the  Test/Demo  Disk  that  comes 
with  the  1571  disk  drive.  It  also  redefines  the  Fl,  F2,  F3,  and 
F5  keys  in  useful  ways.  Fl  will  run  either  version  of  LADS. 
You  can  invoke  it  anywhere  onscreen  because  it  will  cursor 
down  and  clear  the  screen  before  SYS  10000.  F3  will  boot 
RAMLADS  in  case  you  want  a  fresh  start  because  LADS  in 
RAM  became  corrupted.  F2  invokes  AUTO  10,  and  F5  per- 
forms a  SYS  2816  ($B00,  the  start  address  of  many  of  the  ex- 
ample programs  in  this  book).  Each  of  these  functions  clears 
the  screen  in  such  a  way  that  you  can  hit  the  function  key 
anywhere  on  the  screen;  you  need  not  be  on  a  blank  line. 

The  Loader  also  creates  a  small  bit  of  source  code  contain- 
ing a  common  template  for  experimenting  with  a  short 
routine. 
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Program  F-l.  The  Automatic  Proofreader 

10   VEC=PEEK(772)+256*PEEK(773) :L0=43:HI=44 

20    PRINT    "AUTOMATIC    PROOFREADER   FOR    "; :IF  VEC=4236 

4    THEN   PRINT    "C-64" 
30   IF  VEO50556  THEN  PRINT    "VIC-20" 
40    IF  VEC=35158   THEN   GRAPHIC    CLR:PRINT    "PLUS/4    &    1 

6" 
50    IF  VEC=17165    THEN  LO=45 :HI=46:GRAPHIC  CLR:PRINT 

"128" 
60    SA=(PEEK(LO)+256*PEEK(HI))+6:ADR=SA 
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70    FOR  J=0    TO    166: READ    BYT: POKE   ADR, BYT: ADR=ADR+1 : 

CHK=CHK+ BYT : NEXT 
80    IF    CHKO20570    THEN   PRINT    "*ERROR*   CHECK   TYPING 

{SPACE] IN   DATA   STATEMENTS ": END  ,      , 

90    FOR  J=l    TO   5:READ    RF,LF,HF:RS=SA+RF:HB=INT( RS/2  I      I 

56):LB=RS-(256*HB) 
100    CHK=CHK+RF+LF+HF:POKE   SA+LF,LB:POKE   SA+HF,HB:N 

EXT  j      j 

110    IF   CHKO22054    THEN   PRINT    "*ERROR*    RELOAD    PROGR  ' — ' 

AM  AND  CHECK  FINAL  LINE": END 
120  POKE  SA+149,PEEK(772):POKE  SA+150 .PEEK ( 773) 
130  IF  VEC=17165  THEN  POKE  SA+14,22 :POKE  SA+18,23: 

POKESA+29,224:POKESA+139,224 
140   PRINT    CHR$ ( 147 );CHR$( 17); "PROOFREADER   ACTIVE": 

SYS   SA 
150    POKE   HI,PEEK(HI)+l:POKE    ( PEEK(LO)+256*PEEK(HI ) 

)-l,0:NEW 
160    DATA   120,169,73,141,4,3,169,3,141,5,3 
170   DATA  88,96,165,20,133,167,165,21,133,168,169 
180   DATA  0,141,0,255,162,31,181,199,157,227,3 
190   DATA  202,16,248,169,19,32,210,255,169,18,32 
200   DATA   210,255,160,0,132,180,132,176,136,230,180 
210   DATA  200,185,0,2,240,46,201,34,208,8,72 
220  DATA  165,176,73,255,133,176,104,72,201,32,208 
230   DATA  7,165,176,208,3,104,208,226,104,166,180 
240  DATA  24,165,167,121,0,2,133,167,165,168,105 
250    DATA   0,133,168,202,208,239,240,202,165,167,69 
260  DATA   168,72,41,15,168,185,211,3,32,210,255 
270   DATA  104,74,74,74,74,168,185,211,3,32,210 
280  DATA  255,162,31,189,227,3,149,199,202,16,248 
290   DATA  169,146,32,210,255,76,86,137,65,66,67 
300  DATA  68,69,70,71,72,74,75,77,80,81,82,83,88 
310   DATA  13,2,7,167,31,32,151,116,117,151,128,129, 

167,136,137 


Program  F-2.  MLX  U 

U 


AE  100  TRAP  960:POKE  4627,128:DIM  NL$,A(7) 

XP  110  Z2=2:Z4=254:Z5=255:Z6=256:Z7=127:BS=256*PEE 

K(4627):EA=65280 
FB  120  BE$=CHR$(7):RT$=CHR$(13):DL$=CHR$(20):SP$=C 

HR$(32):LF$=CHR$(157) 
KE  130  DEF  FNHB (A)=INT (A/256 ) :DEF  FNLB(A)=A-FNHB (A         j| 

)*256:DEF  FNAD(A)=PEEK(A)+256*PEEK( A+l )  '— ' 

JB  140  KEY  1,"A":KEY  3,"B":KEY  5,"C":KEY  7,"D":VOL 

15:IF  RGR(0)=5  THEN  FAST 
FJ  150  PRINT"{CLR}"CHR$(142);CHR$(8):COLOR  0,15:CO 

LOR  4, 15: COLOR  6,15 
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GQ  160  PRINT  TAB(12)"{RED}{RVS}{2  SPACES} 19    @3 

{2  SPACES}"RT$;TAB(12)"{RVS}{2  SPACES}{OFF} 

{BLU}  128  MLX  {RED}{RVS}{2  SPACES] "RT$ ; TAB ( 

12)"{RVS}{13  SPACES}{BLU}" 
FE  170  PRINT"{2  DOWN}{3  SPACES } COMPUTE  1 ' S  MACHINE 

{SPACE} LANGUAGE  EDITOR{2  DOWN}" 
DK  180  P RI NT "{ BLK} STARTING  ADDRESS &43 "; :GOSUB  260: 

IF  AD  THEN  SA=AD:ELSE  180 
FH  190  PRINT"{BLK}{2  SPACESjENDING  ADDRESSB43 " ; :GO 

SUB  260: IF  AD  THEN  EA=AD:ELSE  190 
MF  200  PRINT "{DOWN} {BLK} CLEAR  WORKSPACE  [Y/N]?g4§" 

:GETKEY  A$:IF  A$<>"Y"  THEN  220 
QH  210  PRINT" {DOWN} {BLUjWORKING. . .";:BANK  0:FOR  A= 

BS  TO  BS+(EA-SA)+7:POKE  A,0:NEXT  A:PRINT"DO 

NE" 
DC  220  PRINT  TAB(10)"{DOWN}{BLK}{RVS}  MLX  COMMAND 

{SPACEjMENU  i4§{D0WN}":PRINT  TAB(13 ) " {RVS}E 

{OFF}NTER  DATA"RT$;TAB(13)"{RVS}D{0FF}ISPLA 

Y  DATA"RT$;TAB(13)"{RVS}L{OFF}OAD  FILE" 
HB  230  PRINT  TAB( 13 ) " {RVS }S{OFF}AVE  FILE "RT$; TAB ( 1 

3 ) " {RVS}C{OFF}ATALOG  DISK"RT$ ;TAB ( 13 ) " {RVS} 

Q{OFF}UIT{DOWN}{BLK}" 
AP  240  GETKEY  A$ :A=INSTR( "EDLSCQ" ,A$ ) :ON  A  GOTO  34 

0,550, 640 ,650 ,930, 940 :GOSUB  950: GOTO  240 
SX  250  PRINT "STARTING  AT";:GOSUB  260 :IF(AD<>0)OR(A 

$=NL$)THEN  RETURN: ELSE  250 
BG  260  A$=NL$:INPUT  A$:IF  LEN(A$)=4  THEN  AD=DEC(A$ 

) 
PP  270  IF  AD=0  THEN  BEGINtIF  A$<>NL$  THEN  300:ELSE 

RETURN: BEND 
MA  280  IF  AD<SA  OR  AD>EA  THEN  300 
PM  290  IF  AD>511  AND  AD<65280  THEN  PRINT  BE$;:RETU 

RN 
SQ  300  GOSUB  950: PRINT "{RVS}  INVALID  ADDRESS 

{ DOWN } { BLK } " : AD=0 : RETURN 
RD  310  CK=FNHB(AD):CK=AD-Z4*CK+Z5*(CK>Z7):GOTO  330 
DD  320  CK=CK*Z2+Z5*(CK>Z7)+A 
AH  330  CK=CK+Z5*(CK>Z5) : RETURN 
QD  340  PRINT  BE$;"{RVS}  ENTER  DATA  ":GOSUB  250  :IF 

{ SPACE }A$=NL$  THEN  220 
JA  350  BANK  0 : PRINT :F=0 :OPEN  3,3 

BR  360  GOSUB  310:PRINT  HEX$(AD)+" : " ; :IF  F  THEN  PRI 

NT  L$:PRINT"{UP}{5  RIGHT}"; 
QA  370  FOR  1=0  TO  24  STEP  3:B$=SP$:FOR  J=l  TO  2:IF 

F  THEN  B$=MID$(L$,I+J,1) 
PS  380  PRINT "{ RVS }"B$+LF$;: IF  K24  THEN  PRINT" 

{OFF}"; 
RC  390  GETKEY  A$:IF  (A$>"/"  AND  A$<":")  OR(A$>"@" 

{ SPACE }AND  A$<"G")  THEN  470 
AC  400  IF  A$="+"  THEN  A$="E":GOTO  470 
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QB  410  IF  A?="-"  THEN  A$="F":GOTO  470 

FB  420  IF  A?=RT?  AND  ((1=0)  AND  (J=l)  OR  F)  THEN  P 

RINT  B?; :J=2:NEXT:I=24:GOTO  480 
RD  430  IF  A?="{HOME}"  THEN  PRINT  B$ :J=2 :NEXT: 1=24 : 

NEXT :F=0: GOTO  360 
XB  440  IF  (A$=" {RIGHT}")  AND  F  THEN  PRINT  B?+LF? ; : 

GOTO  470 
JP  450  IF  A$OLF$  AND  A$<>DL$  OR  ((1=0)  AND  (J=l)) 

THEN  GOSUB  950:GOTO  390 
PS  460  A$=LF$+SP$+LF$: PRINT  B$+LF$ ; :J=2-J :IF  J  THE 

N  PRINT  LF$;: 1=1-3 
GB  470  PRINT  A?;:NEXT  J:PRINT  SP?  ; 
HA  480  NEXT  I :PRINT:PRINT" {UP} {5  RIGHT} "; :L$=" 

(27  SPACES}" 
DP  490  FOR  1=1  TO  25  STEP  3 :GET#3 ,A$ ,B$ :IF  A$=SP$ 

{SPACEjTHEN  1=25 :NEXT:CLOSE  3:GOTO  220 
BA  500  A?=A?+B?:A=DEC(A?):MID?(L?,I,2)=A?:IF  K25 

{ SPACE }THEN  GOSUB  320:A(l/3)=A:GET#3 , A$ 
AR  510  NEXT  I:IF  A<>CK  THEN  GOSUB  950 : PRINT: PRINT" 

{RVS}  ERROR:  REENTER  LINE  ":F=l:GOTO  360 
DX  520  PRINT  BE$:B=BS+AD-SA:FOR  1=0  TO  7:POKE  B+I, 

A(I):NEXT  I 
XB  530  F=0:AD=AD+8:IF  AD<=EA  THEN  360 
CA  540  CLOSE  3 : PRINT" {DOWN} {BLU }**  END  OF  ENTRY  ** 

{BLK}{2  DOWN}":GOTO  650 
MC  550  PRINT  BE$;"{CLR} {DOWN} {RVS}  DISPLAY  DATA  ": 

GOSUB  250: IF  A?=NL?  THEN  220 
JF  560  BANK  0: PRINT "{DOWN} {BLU} PRESS:  {RVS} SPACE 

{OFF}  TO  PAUSE,  { RVS } RETURN { OFF }  TO  BREAK 

§43 {DOWN}" 
XA  570  PRINT  HEX?(AD)+":"; :GOSUB  310 :B=BS+AD-SA 
DJ  580  FOR  I=B  TO  B+7 :A=PEEK( I) : PRINT  RIGHT? (HEX$( 

A),2);SP$;:GOSUB  320:NEXT  I 
XB  590  PRINT" { RVS} "; RIGHT? ( HEX? (CK), 2) 
GR  600  F=1:AD=AD+8:IF  AD>EA  THEN  PRINT" {BLU} **  END 

OF  DATA  **":GOTO  220 
EB  610  GET  A$:IF  A$=RT$  THEN  PRINT  BE$:GOTO  220  |   ( 

QK  620  IF  A$=SP$  THEN  F=F+1: PRINT  BE$; 
XS  630  ON  F  GOTO  570,610,570 
RF  640  PRINT  BE?" {DOWN} {RVS }  LOAD  DATA  ":OP=l:GOTO 

660 
BP  650  PRINT  BE?" {DOWN} {RVS}  SAVE  FILE  ":OP=0 
DM  660  F=0:F?=NL?:INPUT"FILENAMEB41";F?:IF  F?=NL? 

{SPACEjTHEN  220 
RF  670?  PRINT "{ DOWN }{ BLK }{ RVS }T{ OFF} APE  OR  {RVSjD 

{OFF}ISK:  &4§"; 
SQ  680  GETKEY  A?:IF  A?="T"  THEN  850:ELSE  IF  A?o"D        i  . 

"  THEN  680  I I 

SP  690  PRINT"DISK{DOWN}":IF  OP  THEN  760 

EH  700  DOPEN#l, (F?+",P"),W:IF  DS  THEN  A?=D? :GOTO  7 
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! — f      JH  710  BANK  0:POKE  BS-2 ,FNLB(SA) :POKE  BS-1,FNHB(SA 
.'  >  ):  PRINT  "SAVING  ";F$:PRINT 

MC  720  FOR  A=BS-2  TO  BS+EA-SA: PRINT* 1 ,CHR$ (PEEK( A) 

)?:IF  ST  THEN  A$="DISK  WRITE  ERROR":GOTO  75 

0 
GC  730  NEXT  A:CLOSE  1 : PRINT " {BLU} **  SAVE  COMPLETED 

WITHOUT  ERRORS  **":GOTO  220 
RA  740  IF  DS=63  THEN  BEGIN:CLOSE  1 : INPUT " {BLKjREPL 

ACE  EXISTING  FILE  [Y/N]g43n ; A$ :IF  A$=nY"  TH 

EN  SCRATCH (F$): PRINT: GOTO  700:ELSE  PRINT" 

{BLK}":GOTO  660: BEND 
GA  750  CLOSE  l:GOSUB  950 : PRINT " {BLK} {RVS}  ERROR  DU 

RING  SAVE:  B43":PRINT  A$:GOTO  220 
FD  760  DOPEN#l, (F$+",P") :IF  DS  THEN  A$=DS$ :F=4:CLO 

SE  l:GOTO  790 
PX  770  GET* 1,A$,B$: CLOSE  1 :AD=ASC(A$ )+256*ASC (B$ ) : 

IF  AD<>SA  THEN  F=l:GOTO  790 
KB  780  PRINT "LOADING  " ;F$ : PRINT :BLOAD(F$ ) ,B0,P(BS) 

:AD=SA+FNAD(174)-BS-1:F=-2*(AD<EA)-3*(AD>EA 

) 
RQ  790  IF  F  THEN  800:ELSE  PRINT" {BLU} **  LOAD  COMPL 

ETED  WITHOUT  ERRORS  **":GOTO  220 
ER  800  GOSUB  950: PRINT "{BLK} {RVS}  ERROR  DURING  LOA 

D:  B4l":ON  F  GOSUB  810,820,830,840 :GOTO220 
QJ  810  PRINT "INCORRECT  STARTING  ADDRESS  (";HEX$(AD 

);")":RETURN 
DP  820  PRINT"LOAD  ENDED  AT  " ;HEX$ (AD) : RETURN 
EB  830  PRINT "TRUNCATED  AT  ENDING  ADDRESS  ("HEX$(EA 

)")":RETURN 
FP  840  PRINT"DISK  ERROR  ";A$:RETURN 
KS  850  PRINT "TAPE " :AD=POINTER(F$ ) : BANK  1:A=PEEK(AD 

) :AL=PEEK(AD+1) :AH=PEEK(AD+2 ) 
XX  860  BANK  15:SYS  DEC( "FF68" ) ,0,1 :SYS  DEC("FFBA") 

,1,1,0:SYS  DEC("FFBD"),A,AL,AH:SYS  DEC("FF9 

0"), 128: IF   OP   THEN   890 
FG    870    PRINT :A=SA:B=EA+1 :GOSUB   920:SYS    DEC("E919") 

,3 : PRINT "SAVING    " ; F$ 
AB   880    A=BS:B=BS+(EA-SA)+1: GOSUB   920:SYS    DEC("EA18 

"):PRINT" {DOWN} {BLU}**    TAPE    SAVE    COMPLETED 

{SPACE}**": GOTO   220 
CP    890    SYS    DEC("E99A"):PRINT:IF   PEEK(2816)=5    THEN 

{ SPACE JGOSUB   950: PRINT "{DOWN} {BLK} {RVS}    FIL 

E   NOT    FOUND    ":GOTO   220 
GQ    900    PRINT"LOADING    ... {DOWN} " :AD=FNAD( 2817 ) :IF   A 

D<>SA   THEN    F=l:GOTO    800:ELSE   AD=FNAD( 2819) - 

1:F=-2*(AD<EA)-3*(AD>EA) 

, ,      SH  910  A=BS:B=BS+(EA-SA)+l:GOSUB  920: SYS  DEC("E9FB 

/  i,  "):IF  ST  THEN  800:ELSE  790 

XB  920  POKE193,FNLB(A):POKE194,FNHB(A):POKE  174, FN 

LB(B):POKE  175 ,FNHB (B) :RETURN 
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JE    950    SOUND    1,500, 10: RETURN 

AF   960    IF  ER=14   AND   EL=260    THEN   RESUME    300 

MK   970    IF  ER=14   AND   EL=500   THEN   RESUME   NEXT 

KJ    980    IF   ER=4   AND   EL=780    THEN   F=4:A$=DS$ : RESUME    8 

00 
DQ    990    IF   ER=30    THEN   RESUME:ELSE   PRINT    ERR$(ER);" 

{ SPACE }ERROR   IN   LINE"; EL 


u 
u 


u 


CP    930    CATALOG:PRINT"{DOWN}{BLU}**    PRESS    ANY   KEY    F 

OR  MENU    **":GETKEY  A$:GOTO    220 
MM   940    PRINT    BE$" {RVS}    QUIT    &4§" ; RT$ ; "ARE   YOU    SURE 
[Y/N]?":GETKEY  A$:IF  A$<>"Y"    THEN   220:ELSE 
PRINT" {CLR}": BANK   15: END  I     { 

ruivm    n     cam    iffi.cciniiiiKT  '       ' 


u 


Program  F-3.  LADS  Object  Code 

This  listing  must  be  entered  using  the  MIX  program  above. 

Starting  Address:  2710 
Ending  Address:  3D27 

2710 :A9   00   8D   00   FF  8D   IF   3D   96 

2718 :A0   30   99   D9    3C  88   D0   FA  34 

2720 :A9    10   85    FC   85    39   8D   Fl    E5 

2728 :3C  A9    27    85    FD   85    3A  8D  44 

2730 :F2    3C  A9   01    8D   07    3D   EA  3 A 

2738 :EA  EA   20    B8    2F  A9   00    8D  F3 

2740 :DF    3C    20   88    30  AD   F4   3C    78 

2748 :D0   47   A9   93   20   D2   FF  A9    35 

2750  :E6    20    D2   FF  A9    4C    20   D2    06 

2758 :FF  A9   41    20   D2   FF  A9   44   69 

2760:20    D2   FF   A9    53    20   D2   FF   CE 

2768:20    97    35    20   97    35    20    97    BE 

2770:35    AD   E8    3C   D0   0B  A9    85    31 

2778:85    87   A9    3B  85    88    20   FB   DE 

2780:2F  AD   E2    3C   85    FA  8D   DB   01 

2788 :3C  AD  E3   3C  85   FB   8D  DC  B4 

2790 :3C    20   El    FF   D0    03   4C   Bl    IE  [     / 

2798 :2A  AD   DF   3C   F0    03    4C   Bl    05  < — > 

27A0:2A   20    88    30  A9   00   8D   E7    70 

27A8:3C   8D   F3    3C  AC   F4    3C   D0    3D 

27B0:03   4C   D0    27    8C   08    3D  AD   CC 

27B8:06    3D   F0   0C   20   A0    35    20   46 

27C0:51    35    20    79    35    20    51    35   A2 

27C8:AD   FF    3C   F0   03    20   6B   34    28  \     > 

27D0:4C   6A   2F  AD   DA   3C   F0   17    61  i ) 

27D8:C9  03  D0  72  A9  01  8D  DA  55 
27E0:3C  AD  88  3B  D0  68  A9  08  01 
27E8:18  6D  D9  3C  8D  D9  3C  4C  36 
27F0:C7  29  AD  F4  3C  F0  39  A0  2B 
27F8:FF   C8   B9   85    3B   F0    2E   99    9C 
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2800 :D7  3B  C9  20  D0  F3  C8  B9  E7 

2808:85  3B  C9  3D  D0  03  4C  F7  1A 

2810:29  A2  00  8E  08  3D  8A  99  6A 

2818 :D7  3B  B9  85  3B  P0  08  9D  PD 

2820:85  3B  E8  C8  4C  1A  28  9D  64 

2828:85  3B  4C  D0  27  20  D5  2C  32 

2830:20  77  2C  4C  D0  27  AD  9A  Dl 

2838 :3B  C9  40  B0  06  AD  9B  3B  05 

2840 :EE  F3  3C  49  80  8D  E0  3C  59 

2848:20  22  2D  4C  CF  28  A0  00  FB 

2850 :8C  E7  3C  AD  88  3B  C9  20  28 

2858 :F0  03  4C  94  2B  B9  89  3B  43 

2860 :C9  41  90  03  EE  E7  3C  99  51 

2868 :9A  3B  C8  B9  89  3B  F0  16  BA 

2870:99  9A  3B  C9  41  90  03  EE  79 

2878 :E7  3C  C8  B9  89  3B  F0  06  Al 

2880:99  9A  3B  4C  7A  28  88  8C  82 

2888 :E6  3C  AD  E8  3C  D0  40  AD  F2 

2890 :E7  3C  D0  A2  A9  9A  85  87  72 

2898 :A9  3B  85  88  A0  00  AD  9A  C0 

28A0:3B  C9  30  B0  07  18  E6  87  FF 

28A8:90  02  E6  88  Bl  87  F0  10  C4 

28B0:C9  29  F0  0C  C9  2C  F0  08  F7 

28B8:C9  20  F0  04  C8  4C  AC  28  4D 

28C0:48  98  48  A9  00  91  87  20  74 

28C8:FB  2F  68  A8  68  91  87  AD  C0 

28D0:9A  3B  C9  23  F0  3F  C9  28  E8 

28D8:F0  17  AD  DA  3C  C9  08  F0  D4 

28E0:37  C9  03  D0  71  A9  08  18  07 

28E8:6D  D9  3C  8D  D9  3C  4C  C7  E6 

28F0:29  AC  E6  3C  B9  9A  3B  C9  1A 

28F8:29  F0  10  AD  DA  3C  C9  01  53 

2900 :D0  09  A9  10  18  6D  D9  3C  99 

2908 :8D  D9  3C  AD  DA  3C  C9  06  5B 

2910 :F0  53  4C  8C  29  4C  A7  29  F4 

2918: AD  F4  3C  D0  03  4C  8C  29  9E 

2920:38  AD  E2  3C  E5  FA  48  AD  73 

2928 :E3  3C  E5  FB  B0  0E  C9  FF  49 

2930 :F0  04  68  4C  5D  2C  68  10  4A 

2938 :0C  4C  48  29  F0  04  68  4C  F3 

2940 :5D  2C  68  10  03  4C  5D  2C  8A 

2948:38  E9  02  8D  E2  3C  A9  00  A5 

2950 :8D  E3  3C  4C  8C  29  AC  E6  F7 

2958 :3C  88  B9  9A  3B  C9  2C  D0  F5 

2960:04  C8  4C  3F  2B  AD  D9  3C  64 

2968 :C9  4C  D0  03  4C  95  29  AD  B5 

2970 :E3  3C  D0  59  AD  DA  3C  C9  8E 

2978:09  F0  52  C9  06  B0  0D  C9  49 

2980:02  F0  09  A9  04  18  6D  D9  01 

2988 :3C  8D  D9  3C  20  B2  34  20  AF 
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2990 :D3  34  4C  F7  29  AC  E6  3C  E8 

2998 :B9  9A  3B  C9  29  D0  05  A9  B2 

29A0:6C  8D  D9  3C  4C  Fl  29  AD  B5 

29A8:9B  3B  C9  22  D0  06  AD  9C  89 

29B0:3B  8D  E2  3C  AD  DA  3C  C9  3F 

29B8:01  D0  Dl  A9  08  18  6D  D9  E9 

29C0:3C  8D  D9  3C  4C  8C  29  20  9A 

29C8:B2  34  4C  F7  29  AD  DA  3C  7C 

29D0:C9  02  F0  04  C9  07  D0  0C  FE 

29D8:AD  D9  3C  18  69  08  8D  D9  El 

29E0.-3C  4C  Fl  29  C9  06  B0  09  06 

29E8:AD  D9  3C  18  69  0C  8D  D9  02 

29F0:3C  20  B2  34  20  ED  34  AD  Dl 

29F8:F4  3C  D0  03  4C  AE  2A  AD  3E 

2A00:06  3D  D0  03  4C  AE  2A  AD  10 

2A08:08  3D  D0  3E  AD  02  3D  F0  8E 

2A10:2A  A9  14  38  E5  EC  8D  F5  DD 

2A18:3C  20  CC  FF  A2  04  20  C9  5B 

2A20:FF  AC  F5  3C  10  05  A0  02  F9 

2A28:4C  2D  2 A  A9  20  20  D2  FF  F4 

2A30:88  D0  FA  20  CC  FF  A2  01  0B 

2A38:20  FA  2F  A9  14  85  EC  A9  16 

2A40:D7  85  87  A9  3B  85  88  20  8E 

2A48:40  35  A9  IE  38  E5  EC  8D  El 

2A50:F6  3C  A9  IE  85  EC  AD  02  83 

2A58.-3D  F0  1A  20  CC  FF  A2  04  7C 

2A60:20  C9  FF  AC  F6  3C  F0  0A  96 

2A68:30  08  A9  20  20  D2  FF  88  E2 

2A70:D0  FA  20  CC  FF  20  AD  35  CD 

2A78:AD  00  3D  F0  11  C9  01  D0  DC 

2A80:05  A9  3C  4C  88  2A  A9  3E  8C 

2A88:20  D2  FF  20  El  35  AD  09  EB 
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3350:02  3D  8E  09  3D  4C  87  33  C6 

3358 :8D  AE  3B  AD  F4  3C  D0  0D  BA 

3360: AD  AE  3B  C9  20  D0  CB  20  49 

3368:38  35  4C  32  33  AD  AE  3B  CD 

3370:99  85  3B  C8  C9  20  F0  18  CI 

3378 :C9  00  F0  14  C9  3A  F0  10  4C 

3380 :9D  E7  3B  E8  4C  32  33  EE  26 

3388 :FB  3C  8D  AF  3B  4C  58  33  97 

3390 :A9  E7  85  87  A9  3B  85  88  BC 

3398 :8C  F7  3C  20  FB  2F  AE  E2  A9 

33A0:3C  20  23  35  AC  F7  3C  A9  4C 

33A8:00  A2  05  9D  E7  3B  CA  D0  C4 

33B0:FA  4C  32  33  AD  F4  3C  D0  AB 

33B8:03  20  38  35  AD  AF  3B  C9  6F 

33C0:3A  F0  03  20  D8  31  8D  04  8D 

33C8:3D  EE  08  3D  68  68  AD  F4  93 

33D0:3C  F0  08  AD  06  3D  F0  03  77 

33D8:4C  75  2A  4C  91  27  48  A9  30 

33E0:00  8D  5B  34  A9  02  8D  5C  26 

33E8:34  68  20  08  34  48  A9  85  A3 

33F0:8D  5B  34  A9  3B  8D  5C  34  13 

33F8:68  60  A9  BF  85  87  A9  3C  B6 

3400:85  88  20  40  35  4C  C6  2A  E7 

3408 :8C  F5  3C  38  E9  7F  A0  17  E4 

3410:84  8E  A0  44  84  8F  C9  4F  FB  i  i 

3418 :D0  11  A0  C9  84  8E  A0  46  C3  I S 

3420:84  8F  20  E2  2F  A8  88  98  A6 

3428 :4C  3D  34  C9  7F  D0  0E  A0  25 

3430:09  84  8E  A0  46  84  8F  20  9D  j  ( 

3438  :E2  2F  A8  88  98  AA  A0  00  2C  ' — ' 

3440 :CA  F0  0E  Bl  8E  48  E6  8E  19 

3448 :D0  02  E6  8F  68  10  F4  30  0D  ,  , 

3450 :EF  AE  F5  3C  A0  00  Bl  8E  D5  { \ 

3458:30  07  9D  85  3B  C8  E8  D0  46 

3460 :F5  29  7F  8E  F7  3C  AC  F7  E8 
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34D8:20  38  35  60  AD  06  3D  F0  FC 

34E0:06  AE  E2  3C  20  5A  35  AE  9B 

34E8:E2  3C  4C  23  35  AD  F4  3C  14 

34F0:D0  07  20  38  35  20  38  35  DA 

34F8:60  AD  06  3D  F0  06  AE  E2  71 

3500 :3C  20  5A  35  AE  E2  3C  20  C8 

3508:23  35  AD  06  3D  F0  0E  AD  DE 

3510:07  3D  F0  03  20  51  35  AE  FA 

3518 :E3  3C  20  5A  35  AE  E3  3C  95 

3520 :4C  23  35  8E  El  3C  AD  03  67 
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3588:20  3C  36  60  A6  FA  A5  FB  47 
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3598 :0D  20  2D  C7  20  D5  35  60  D6 
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I  j      35A8:8E  20  79  36  60  A9  85  85  2F 
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J J       35E0:60  AE  02  3D  D0  04  AE  F6  26 
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3620:07  3D  F0  09  AD  F6  3C  20  EF 
3628 :A6  36  4C  35  36  A9  00  AE  59 
3630 :F6  3C  20  32  8E  20  CC  FF  DC 
3638:20  C6  36  60  20  BF  36  AE  4E 
3640 :F4  3C  D0  04  AE  F6  3C  60  BA 
3648 :AE  02  3D  D0  04  AE  F6  3C  46 
3650:60  20  CC  FF  A2  04  20  C9  BD 
3658 :FF  AE  07  3D  F0  0D  A5  FB  28 
3660:20  A6  36  A5  FA  20  A6  36  83 
3668 :4C  72  36  A5  FB  A6  FA  20  49 
3670:32  8E  20  CC  FF  20  C6  36  AE 
3678:60  20  BF  36  AE  F4  3C  D0  0B 
3680:04  AE  F6  3C  60  AE  02  3D  3C 
3688 :D0  04  AE  F6  3C  60  20  CC  14 
3690 :FF  A2  04  20  C9  FF  AD  DE  B0 
3698 :3C  AE  DD  3C  20  32  8E  20  55 
36A0:CC  FF  20  C6  36  60  48  29  D0 
36A8:0F  A8  B9  75  3B  AA  68  4A  F4 
36B0:4A  4A  4A  A8  B9  75  3B  20  E2 
36B8:D2  FF  8 A  20  D2  FF  60  8D  C6 
36C0:F5  3C  8C  F7  3C  60  AD  F5  FC 
36C8:3C  AC  F7  3C  60  C9  46  D0  C8 
36D0:08  20  30  37  68  68  4C  91  Dl 
36D8:27  C9  80  D0  06  20  7A  37  45 
36E0:4C  D4  36  C9  44  D0  03  4C  C3 
36E8:C4  37  C9  50  D0  03  4C  24  13 
36F0:39  C9  4E  D0  03  4C  58  39  76 
36F8:C9  4F  D0  03  4C  50  39  C9  48 
3700:53  D0  03  4C  10  3A  C9  48  B6 
3708 :D0  03  4C  2A  3A  99  85  3B  4A 
3710:20  A0  35  20  51  35  20  79  78 
3718:35  20  B9  35  20  AD  35  A9  7F 
3720 :A5  85  87  A9  3C  85  88  20  77 
3728:40  35  20  97  35  4C  37  39  04 
3730:20  E2  2F  C9  20  F0  03  4C  01  , 

3738:30  37  A0  00  20  E2  2F  C9  55  1 \ 

3740:00  F0  0E  C9  7F  90  03  20  AD 

3748:08  34  99  85  3B  C8  4C  3C  25 

3750:37  8C  EA  3C  A0  00  B9  85  9C  \     | 

3758 :3B  F0  07  99  D7  3B  C8  4C  A4  *~ ' 

3760:56  37  20  79  35  20  51  35  65 

3768:20  AD  35  20  97  35  20  4B  18  , 

3770 :2E  20  E2  2F  A2  00  8E  DF  5F  j 

3778 :3C  60  AD  F4  3C  F0  03  4C  1A 

3780 :A9  37  A9  2E  20  D2  FF  A9  9F 

3788:45  20  D2  FF  A9  4E  20  D2  95 

3790 :FF  A9  44  20  D2  FF  A9  20  FD 

3798:20  D2  FF  20  E2  2F  20  3A  1C 
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37A0:37  AD  F4  3C  F0  03  EE  DF  C9 
37A8:3C  EE  F4  3C  AD  F4  3C  C9  D6 
37B0:02  D0  03  4C  3F  3A  AD  DB  93 
37B8:3C  85  FA  AD  DC  3C  85  FB  BF 
37C0:20  88  30  60  EE  03  3D  EE  5A 
37C8:1E  3D  EE  01  3D  20  E2  2F  E2 
37D0:C9  20  F0  F9  A0  00  C9  7F  02 
37D8:90  1C  4C  E8  37  20  E2  2F  DD 
37E0:C9  20  F0  1C  C9  7F  90  0E  97 
37E8:8C  6A  34  48  20  08  34  68  35 
37F0:AC  6A  34  20  4A  3A  99  85  CC 
37F8:3B  99  D7  3B  C8  4C  DD  37  84 
3800 :8C  EA  3C  99  85  3B  A0  00  EC 
3808  :A9  40  99  EE  3B  C8  A9  30  FF 
3810:99  EE  3B  C8  A9  3A  99  EE  55 
3818 :3B  C8  20  E2  2F  F0  2D  C9  EB 
3820 :7F  90  18  48  A9  EE  8D  5B  7B 
3828:34  A9  3B  8D  5C  34  68  8C  6E 
3830 :F7  3C  20  08  34  20  ED  33  61 
3838  :AC  F7  3C  C9  20  F0  DB  99  37 
3840:85  3B  99  EE  3B  C8  4C  1A  14 
3848:38  20  37  39  8C  EB  3C  20  04 
3850 :D8  31  A2  00  8E  DF  3C  A0  DA 
3858:00  B9  0A  3D  99  37  27  C8  0D 
3860:B9  0A  3D  99  37  27  C8  B9  13 
3868 :0A  3D  99  37  27  C8  A9  80  04 
3870 :8D  BD  2F  A9  EA  8D  C0  2F  D5 
3878 :8D  CI  2F  8D  C2  2F  B9  0A  2F 
3880: 3D  C8  8D  ED  2F  B9  0A  3D  04 
3888 :C8  8D  EE  2F  B9  0A  3D  C8  CA 
3890 :8D  EF  2F  B9  0A  3D  C8  8D  A9 
3898 :F0  2F  B9  0A  3D  C8  8D  Fl  3F 
38A0:2F  B9  0A  3D  C8  8D  F2  2F  BD 
38A8:B9  0A  3D  C8  8D  F3  2F  B9  01 
38B0:0A  3D  C8  8D  2B  35  B9  0A  13 
38B8:3D  C8  8D  2C  35  B9  0A  3D  50 
38C0:C8  8D  2D  35  B9  0A  3D  C8  2B 
38C8:8D  2E  35  B9  0A  3D  C8  8D  32 
38D0:2F  35  B9  0A  3D  C8  8D  33  59 
38D8:35  B9  0A  3D  C8  8D  34  35  81 
38E0:B9  0A  3D  C8  8D  35  35  B9  4A 
38E8:0A  3D  C8  8D  36  35  B9  0A  A3 
38F0:3D  8D  37  35  A9  EA  A2  00  DB 
38F8:9D  99  27  E8  E0  08  D0  F8  D3 
3900 :A9  FF  8D  8B  2E  68  68  AD  43 
3908 :1E  3D  C9  01  F0  03  4C  91  DF 
3910:27  A9  91  20  D2  FF  20  D2  5E 
3918 :FF  A9  44  20  IE  C0  20  4B  FE 
3920 :2E  4C  3A  27  AD  F4  3C  F0  21 
3928 :0E   20   05    2F  EE   02    3D   20    57 
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3930 :CC  PF  A9  01  8D  06  3D  20  6D 

3938 :E2  2F  F0  07  C9  3A  F0  06  95 

3940 :4C  37  39  20  D8  31  68  68  94 

3948 :A2  00  8E  DF  3C  4C  91  27  39 

3950 :A9  01  8D  03  3D  4C  37  39  7C  I  I 

3958 :AD  F4  3C  F0  DA  20  E2  2F  CI  1—1 

3960 :C9  50  F0  0C  C9  4F  F0  3A  52 

3968 :C9  53  F0  6A  C9  48  F0  4C  F6 

3970 :A9  2E  20  D2  FF  A9  4E  20  D7  M 

3978  :D2  FF  A9  50  20  D2  FF  20  FA 

3980:97  35  CE  02  3D  20  CC  FF  0A 

3988 :A2  04  20  C9  FF  A9  0D  20  CE 

3990 :D2  FF  A9  04  20  C3  FF  20  12 

3998 :CC  FF  A2  01  20  FA  2F  4C  6D 

39A0:37  39  A9  2E  20  D2  FF  A9  0B 

39A8:4E  20  D2  FF  A9  4F  20  D2  42 

39B0:FF  20  97  35  A9  00  8D  03  DC 

39B8:3D  4C  37  39  A9  2E  20  D2  70 

39C0:FF  A9  4E  20  D2  FF  A9  48  9B 

39C8:20  D2  FF  20  97  35  A9  00  E6 

39D0:8D  07  3D  4C  37  39  A9  2E  58 

39D8:20  D2  FF  A9  4E  20  D2  FF  43 

39E0:A9  53  20  D2  FF  20  97  35  13 

39E8:A9  00  8D  06  3D  4C  37  39  05 

39F0:A6  90  D0  01  60  A9  00  20  CE 

39F8:5A  35  20  51  35  A9  63  85  9B 

3A00:87  A9  3C  85  88  20  B9  35  EF 

3A08:20  40  35  68  68  4C  C6  2A  F5 

3A10:AD   F4   3C    F0    12    A9    2E    20    E2 

3A18:D2   FF  A9    53    20   D2   FF   20   CC 

3A20:97    35   A9   01    8D   06    3D  4C   3E 

3A28:37    39   A9    2E   20   D2   FF  A9    94 

3A30:48    20   D2   FF   20    97    35    A9   9E 

3A38:01    8D   07    3D   4C    37    39    AD  A4 

3A40:01    3D   F0   03    20    B4   2E  4C  4F 

3A48:B1    2 A  48    A9    D7    8D   5B    34   A3 

3A50:A9   3B  8D   5C    34   68    20   08   6B 

3A58:34   20   ED    33    60    4C   44   41    DD 

3A60:4C   44   59   4A   53    52    52    54    B8 

3A68:53    42    43    53    42    45    51    42    C0 

3A70:43  43  43  4D  50  42  4E  45  02  M 

3A78:4C  44  58  4A  4D  50  53  54  7A 

3A80:41  53  54  59  53  54  58  49  70 

3A88:4E  59  44  45  59  44  45  58  16 

3A90:44  45  43  49  4E  58  49  4E  2 A 

3A98:43  43  50  59  43  50  58  53  7E 

3AA0:42  43  53  45  43  41  44  43  B0 

3AA8:43  4C  43  54  41  58  54  41  D4 

3AB0:59  54  58  41  54  59  41  50  E0 
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3AC0:42  4D  49  42  50  4C  41  4E  7B 
3AC8:44  4F  52  41  45  4F  52  42  DF 
3AD0:49  54  42  56  43  42  56  53  CF 
3AD8:52  4F  4C  52  4F  52  4C  53  A8 
3AE0:52  43  4C  44  43  4C  49  41  3C 
3AE8:53  4C  50  48  50  50  4C  50  55 
3AF0:52  54  49  53  45  44  53  45  29 
3AF8:49  54  53  58  54  58  53  43  05 
3B00:4C  56  4E  4F  50  01  05  09  8A 
3B08:00  08  08  08  01  08  05  06  3A 
3B10:01  02  02  00  00  00  02  00  CB 
3B18:02  04  04  01  00  01  00  00  25 
3B20:00  00  00  00  00  00  08  08  AE 
3B28:01  01  01  07  08  08  03  03  59 
3B30:03  00  00  03  00  00  00  00  58 
3B38:00  00  00  00  00  Al  A0  20  96 
3B40:60  B0  F0  90  CI  D0  A2  4C  ID 
3B48:81  84  86  C8  88  CA  C6  E8  E3 
3B50:E6  C0  E0  El  38  61  18  AA  C6 
3B58:A8  8A  98  48  68  00  30  10  11 
3B60:21  01  41  24  50  70  22  62  FC 
3B68:42  D8  58  02  08  28  40  F8  BB 
3B70:78  BA  9A  B8  EA  30  31  32  5D 
3B78:33  34  35  36  37  38  39  41  ED 
3B80:42  43  44  45  46  00  00  00  F7 
3B88:00  00  00  00  00  00  00  00  FE 
3B90:00  00  00  00  00  00  00  00  07 
3B98:00  00  00  00  00  00  00  00  0F 
3BA0:00  00  00  00  00  00  00  00  17 
3BA8:00  00  00  00  00  00  00  00  IF 
3BB0:00  00  00  00  00  00  00  00  27 
3BB8:00  00  00  00  00  00  00  00  2F 
3BC0:00  00  00  00  00  00  00  00  37 
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3BF0:00  00  00  00  00  00  00  00  67 
3BF8:00  00  00  00  00  00  00  00  6F 
3C00:00  00  00  4E  4F  20  53  54  53 
3C08:41  52  54  20  41  44  44  52  38 
3C10:45  53  53  00  2D  2D  2D  2D  10 
3C18:2D  2D  2D  2D  2D  2D  2D  2D  90 
3C20:2D  2D  2D  2D  2D  2D  2D  2D  98 
3C28:20  42  52  41  4E  43  48  20  CF 
3C30:4F  55  54  20  4F  46  20  52  58 
3C38:41  4E  47  45  00  55  4E  44  58 
3C40:45  46  49  4E  45  44  20  4C  C2 
3C48:41  42  45  4C  00  20  20  20  40 
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3C50:20  20  20  20  20  20  20  4E  F6 

3C58:41  4B  45  44  20  4C  41  42  28 

3C60:45  4C  00  20  20  20  20  20  72 

3C68:20  3C  3C  3C  3C  3C  3C  3C  D2 

3C70:3C  20  44  49  53  4B  20  45  79  I 

3C78:52  52  4F  52  20  3E  3E  3E  72 

3C80:3E  3E  3E  3E  3E  20  00  20  E5 

3C88:20  20  20  20  20  2D  2D  20  4F 

3C90:44  55  50  4C  49  43  41  54  7D 

3C98:45  44  20  4C  41  42  45  4C  77 

3CA0:20  2D  2D  20  00  20  20  20  FC 

3CA8:20  20  20  2D  2D  20  53  59  F9 

3CB0:4E  54  41  58  20  45  52  52  20 

3CB8:4F  52  20  2D  2D  20  00  20  4E 

3CC0:20  2E  46  49  4C  45  20  4F  39 

3CC8:52  20  2E  45  4E  44  20  52  A2 

3CD0:45  51  55  49  52  45  44  20  CF 

3CD8:00  00  00  00  00  00  00  00  51 

3CE0:00  00  00  00  00  00  00  00  59 

3CE8:00  00  00  00  00  00  00  00  61 

3CF0:00  00  00  00  00  00  00  00  69 

3CF8:00  00  00  00  00  00  00  00  71 

3D00:00  00  00  00  00  00  00  00  7A 

3D08:00  00  20  4B  2E  A9  41  A2  78 

3D10:00  20  74  FF  A9  FA  8D  B9  2F 

3D18:02  A2  01  20  77  FF  00  00  1A 

3D20:20  45  52  52  4F  52  53  00  D5 


Program  F-4.  Loader 

MH  1  REM  1571  DISK  DRIVE  USERS  SUBSTITUTE  'BOOT'  F 

OR  'BLOAD'  IN  LINES  30  AND  100 
FK  10  PRINT" tCLR} 
GD  20  KEY  l/""+CHR$(17)+CHR$(27)+CHR$(74)+CHR$(27) 

+CHR$(64)+"SYS  10000 "+CHR$( 13) 
BQ  30  KEY  3,""+CHR$(17)+CHR$(27)+CHR$(74)+CHR$(27)        \     I 

+CHR$ ( 64 )  + "BLOAD "+CHR$ ( 34 )  +  "LADS"+CHR$ ( 13 )  ' — ' 

KA  40  KEY  5, ""+CHR$ ( 17 )+CHR$ ( 27 )+CHR$ ( 74)+CHR$( 27 ) 

+CHR$(64)+"SYS  2816"+CHR$(13)  . 

FR  45  KEY  2, ""+CHR$ ( 17 )+CHR$ ( 27 )+CHR$ ( 74)+CHR$ ( 27 )         |i 

+CHR$(64)+"AUTO  10"+CHR$(13) 
BJ  50  FOR  I  =  7169  TO  7224 :READA:POKEI ,A:NEXT 
GP  60  DATA  13,28,10,0,172,178,32,36,66,48,48,0,20,        \     | 

28,20,0,46,83,0,27,28,30,0,46,79,0,49  L_J 

PP  70  DATA  28,40,0,59,32,32,32,32,80,82,79,71,82,6 

5,77,32,78,65,77,69,0,55,28,50,0,59,0,0,0 
SG  100  PRINT" {CLRj "; : BLOAD  "LADS 
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Commodore  ASCII  Codes 


Dec     Hex     Uppercase/Graphics  Set    Lowercase/Uppercase  Set 

underline  on1 

white 

bell  tone2 

disable  SHIFT-Commodore3 

tab2 
enable  SHIFT-Commodore3 

linefeed2 

disable  SHIFT-Commodore2 

enable  SHIFT-Commodore2 

RETURN 

switch  to  lowercase 

flash  on1 

cursor  down 

reverse  on 

home 

delete 

tab  set/clear2 

ESCape 

red 

cursor  right 

green 

blue 

space 

!  ! 

//  // 

#  # 

$  $ 

%  % 

38      26  &  & 
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2 

02 

5 

05 

7 

07 

8 

08 

9 

09 

10 

0A 

11 

0B 

12 

0C 

13 

0D 

14 

0E 

15 

OF 

17 

11 

18 

12 

19 

13 

20 

14 

24 

18 

27 

IB 

28 

1C 

29 

ID 

30 

IE 

31 

IF 

32 

20 

33 

21 

34 

22 

35 

23 

36 

24 

37 

25 

Appendix  G 


40 

28 

( 

41 

29 

) 

42 

2A 

* 

43 

2B 

+ 

44 

2C 

/ 

45 

2D 

— 

46 

2E 

. 

47 

2F 

/ 

48 

30 

0 

49 

31 

1 

50 

32 

2 

51 

33 

3 

52 

34 

4 

53 

35 

5 

54 

36 

6 

55 

37 

7 

56 

38 

8 

57 

39 

9 

58 

3A 

; 

59 

3B 

/ 

60 

3C 

< 

61 

3D 

= 

62 

3E 

> 

63 

3F 

? 

64 

40 

@ 

65 

41 

A 

66 

42 

B 

67 

43 

C 

68 

44 

D 

69 

45 

E 

70 

46 

F 

( 
) 

* 

+ 


/ 

0 

1 

2 
3 
4 
5 
6 
7 
8 
9 


> 
? 

@ 

a 

b 
c 
d 
e 

f 


LI 
U 
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Dec  Hex     Uppercase/Graphics  Set   Lowercase/Uppercase  Set 

71  47  G  g 

72  48  H  h 

73  49  I  i 

74  4A  J  j 

75  4B  K  k 

76  4C  L  1 

77  4D  M  m 

78  4E  N  n 

79  4F  O  o 

80  50  P  p 

81  51  Q  q 

82  52  R  r 

83  53  S  s 

84  54  T  t 

85  55  U  u 

86  56  V  v 

87  57  W  w 

88  58  X  x 

89  59  Y  y 

90  5A  Z  z 

91  5B  [  [ 

92  5C  £  £ 

93  5D  ]  ] 

94  5E  t  t 

95  5F 


96     60 


a  e 

;     '•■  97  61  S  A 

98  62  d  B 

f*J  99  63  H  C 

100  64  H  D 

(— ]  101  65  H  E 

'     '  102  66  H  F 

i     I  381 
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103 

67 

E 

G 

104 

68 

[I] 

H 

105 

69 

ffl 

I 

106 

6A 

a 

J 

107 

6B 

a 

K 

108 

6C 

L 

L 

109 

6D 

S 

M 

110 

6E 

0 

N 

111 

6F 

c 

O 

112 

70 

a 

P 

113 

71 

m 

Q 

114 

72 

y 

R 

115 

73 

h 

S 

116 

74 

c 

T 

117 

75 

a 

U 

118 

76 

X 

V 

119 

77 

o 

W 

120 

78 

SI 

X 

121 

79 

a 

Y 

122 

7A 

a 

Z 

123 

7B 

+ 

S 

124 

7C 

B 

B 

125 

7D 

CE 

m 

126 

7E 

H 

& 

127 

7F 

H 

S? 

129 

81 

orange4 
dark  purple1 

130 

82 

underline  off1 

133 

85 

Fl 

134 

86 

F3 

135 

87 

F5 

136 

88 

F7 

u 
u 
u 
u 
u 


u 

U 

u 
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137 

89 

F2 

138 

8A 

F4 

139 

8B 

F6 

140 

8C 

F8 

141 

8D 

SHIFT-RETURN 

142 

8E 

switch  to  uppercase 

143 

8F 

flash  off1 

144 

90 

black 

145 

91 

cursor  up 

146 

92 

reverse  off 

147 

93 

clear  screen 

148 

94 

insert 

149 

95 

brown4 
dark  yellow1 

150 

96 

light  red 

151 

97 

dark  gray4 
dark  cyan1 

152 

98 

medium  gray 

153 

99 

light  green 

154 

9A 

light  blue 

155 

9B 

light  gray 

156 

9C 

purple 

157 

9D 

cursor  left 

158 

9E 

yellow 

159 

9F 

cyan 

160 
161 
162 
163 
164 
165 

A0 
Al 
A2 
A3 

A4 
A5 

1 
- 

□ 

SHIFT-space 

c 

y 

n 
□ 

166      A6  SB  §H 
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167  A7  □  □ 

168  A8  H  H  I     / 

169  A9  B  ^  ^J 

170  AA  □  [] 

171  AB  m  \E  Li 

172  AC  Q  Q 

173  AD  H  H 

174  AE  H  ffl 

175  AF  Q  □ 

176  BO  ffl  ffl 

177  Bl  h  a 

178  B2  ffl  ffi 

179  B3  ai  ai 

180  B4  D  [] 

181  B5  C  [] 

182  B6  [1  [J 

183  B7  □  n 

184  B8  H  H' 

185  B9  U  U 

186  BA  □  0 

187  BB  £]  0 

188  BC  g  g 

189  BD  J]  3] 

190  BE  H  J]  M 

191  bf  5  5g 

192  CO  g  g  ,    ^ 

193  CI  g  A  UJ 

194  C2  (J  B 

195  cs  a  C  Li 

196  C4  Q  D 

197  C5  g  E 

198  C6  g  F 
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E  G 

[X  •      H 

B  i 

—               202      CA                        ffl  J 

PI                   903        PR                                 H  K 


199  C7 

200  C8 

201  C9 


230      E6 


U  L 

K  M 


203  CB 

204  CC 

205  CD 

206  CE  2!  N 

207  CF  C  O 

208  DO  0  P 

209  Dl  HI  Q 

210  D2  B  R 

211  D3  H  s 

212  D4  C  T 

213  D5  ffl  u 

214  D6  8  v 

215  D7  HI  w 

216  D8  SI  X 

217  D9  [J  Y 

218  DA  91  Z 

B  B 


219  DB 

220  DC 

221  DD 

222  DE  H 

223  DF  H 


224  E0  D  D 

225  El  B  D 

226  E2  y  H 

H.       227  E3  n  n 

228  E4  D  -  □ 

R                229  E5  D  D 
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□ 


□ 

OB 
Q 
ffl 
ffl 
-j 
ffl 

a 
s 

9] 
C 
E 

a 

□ 

H 
U 
0 
. 

a 

E 


231      E7 

□ 

232     E8 

V. 

233      E9 

B 

234      EA 

□ 

235      EB 

□B 

236     EC 

Q 

237      ED 

ffl 

238      EE 

ffl 

239      EF 

y 

240      F0 

a 

241      Fl 

a 

242      F2 

a 

243      F3 

§c 

244      F4 

c 

245      F5 

c 

246      F6 

a 

247     F7 

n 

248      F8 

H 

249      F9 

u 

250      FA 

LI 

251      FB 

E 

252      FC 

a 

253      FD 

a 

254      FE 

E 

255      FF 

H 

Notes 

1.  80-column  display  only 
2. 128  mode  only 

3.  64  mode  only 

4.  40-column  display  only 

u 
u 
u 
u 
u 
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True  ASCn 

ASCII 

ASCII 

ASCII 

Code 

Character 

Code 

Character 

Code 

Character 

0 

NUL 

44 

/ 

86 

V 

1 

SOH 

45 

— 

87 

w 

2 

STX 

46 

, 

88 

X 

3 

ETX 

47 

/ 

89 

Y 

4 

EOT 

48 

0 

90 

Z 

5 

ENQ 

49 

1 

91 

[ 

6 

ACK 

50 

2 

92 

\ 

7 

BEL 

51 

3 

93 

] 

8 

BS 

52 

4 

94 

a 

9 

HT 

53 

5 

95 

_ 

10 

LF 

54 

6 

96 

- 

11 

VT 

55 

7 

97 

a 

12 

FF 

56 

8 

98 

b 

13 

CR 

57 

9 

99 

c 

14 

SO 

58 

; 

100 

d 

15 

SI 

59 

/ 

101 

e 

16 

DLE 

60 

< 

102 

f 

17 

DC1 

61 

= 

103 

g 

18 

DC2 

62 

> 

104 

h 

19 

DC3 

63 

? 

105 

i 

20 

DC4 

64 

@ 

106 

j 

21 

NAK 

65 

A 

107 

k 

22 

SYN 

66 

B 

108 

1 

23 

ETB 

67 

C 

109 

m 

24 

CAN 

68 

D 

110 

n 

25 

EM 

69 

E 

111 

0 

26 

SUB 

70 

F 

112 

P 

27 

ESC 

71 

G 

113 

q 

28 

FS 

72 

H 

114 

r 

29 

GS 

73 

I 

115 

s 

30 

RS 

74 

J 

116 

t 

31 

US 

75 

K 

117 

u 

32 

(space) 

76 

L 

118 

V 

33 

! 

77 

M 

119 

w 

34 

// 

78 

N 

120 

X 

35 

# 

79 

O 

121 

y 

36 

$ 

80 

P 

122 

z 

37 

% 

81 

Q 

123 

{ 

38 

& 

82 

R 

124 

1 

39 

' 

83 

S 

125 

} 

40 

( 

84 

T 

126 

41 

) 

85 

U 

127 

DEL 

42 

• 

43 

+ 
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LJ 
U 
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u 
u 
u 

u 


n 

n 

n 


Index 
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A  (Assemble)  monitor  instruction  31-32 
absolute,  X  addressing  67-69 
absolute,  Y  addressing  67-69 
absolute  addressing  58 
accumulator  24,  25,  55-56,  80 
accumulator  mode  addressing  72 
ADC  instruction  25,  80,  97,  146, 

215-16 
adding  large  numbers  81-84 
addition  80-84 
addressing  21-22 

modes  53-72 
address  pointer  69 
AND  instruction  123,  124,  216-17 
Apple  computers  31 
argument  xi,  78 
arithmetic  75-87 

in  ML  24-25 
Arithmetic  instruction  group  97-98 
ASC  BASIC  function,  ML  equivalent  of 

182-83 
ASCII,  true  387 
ASCII  code  13,  75,  76,  109 
ASL  instruction  72,  85,  97,  124,  217 
assembler  ix,  21.  See  also  LADS 
assembly,  disk  142 
assembly  language  ix.  See  also  LADS 
*=  pseudo-op  252-53 
"Automatic  Proofreader,  The"  program 

351-53,  359-60 
bank  15,  21,  31,  39,  191,  192-95 
Bank  Number  Code  ROM  routine  209 
bank  switching  191-92,  195-96 
BASIC 

borrowing  from  129-35 

commands,  ML  equivalents  of 

157-87 

use  for  complicated  arithmetic  75 

versus  ML  xii-xiv 
"BASIC  Loader"  program  23-24 
BCC  instruction  64,  85,  87,  98,  101,  218 
BCS  instruction  64,  85,  87,  98,  101,  218 
BEQ  instruction  55,  64,  85,  98-99, 101, 

218-19 
big  loops  107-8 
binary  notation  11 
"Binary  Quiz"  program  1-2 
"Binary  Table"  program  20 
bit  12,  16 

BIT  instruction  124,  219 
BLOAD  BASIC  command  37 


BMI  instruction  64,  85,  87,  98,  101, 

105,  219-20 
BNE  instruction  64,  85,  87,  96,  99-101, 

105,  220 
book,  how  to  use  3-7 
BPL  instruction  64,  85,  87,  98,  101, 

105,  220-21 
branching  98-105 
BRK  instruction  33,  36,  37,  46,  63,  64, 

87,  96, 120-22,  221 
built-in  routines.  See  ROM  routines 
BVC  instruction  64,  91,  98,  101,  222 
BVS  instruction  64,  98,  101,  222 
byte  13-14,  16,  17-19 
.BYTE  pseudo-op  253-54 
carry  flag  80-81,  87 
cassette 

buffer  140-41 

tape  259 
C  (Compare  Memory)  monitor  instruc- 
tion 32 
C  flag  97 

chained  files,  LADS  and  259-62 
character  codes,  Commodore  379-86 
CHR$  BASIC  function,  ML  equivalent 

of  183 
CLC  instruction  61,  97, 146,  222-23 
CLD  instruction  61,  223 
CLI  instruction  125,  223 
CLOSE  ROM  routine  203 
CLR  BASIC  command,  ML  equivalent 

of  157-58 
CLV  instruction  91,  224 
CMP  instruction  13,  85,  87,  99,  105, 

194,  224-25 
CMP  long  ROM  routine  193,  211 
comparison  subroutine  344 
compiled  code  131 
CONT  BASIC  command,  ML  equiva- 
lent of  158-59 
CPX  instruction  99,  225-26 
CPY  instruction  99,  226-27 
cursor  control  ROM  routine  207-8 
customize  function  keys  ROM  routine 

208-9 
database,  searching  85 
DATA  BASIC  command,  ML  equivalent 

of  159-60 
data  tables  252 
D  (Disassemble)  monitor  instruction 

32-35 


389 


Debugger  instruction  group  120-22 
debugging  xiv,  42-46,  120-22 

monitor  and  31,  34,  46 
DEC  instruction  69,  106,  227 
Decision  Maker  instruction  group 

98-105 
DEX  instruction  63,  106,  227-28 
DEY  instruction  63,  69,  106,  228 
DIM  BASIC  command,  ML  equivalent 

of  160-61 
disassembly  xi-xii,  24-25,  32-35 
division  84-85 
division  subroutine  348 
double-byte  addition  subroutine  345 
double-byte  subtraction  subroutine 

345-46 
"Double-Compare"  program  86-87 
double  comparison  85-87 
.D  pseudo-op  261 
80-column  mode  4 
8502  chip  13,  125-26 
8502  instruction  set  215-46 
"Embedded  PRINT"  program  205 
END  BASIC  command,  ML  equivalent 

of  161-62 
endless  loop  45 
.END  pseudo-op  260 
environment,  128  191-97 
EOR  instruction  123-24,  228-29 
ESCape  key,  ML  and  191-92 
F  (fill)  monitor  instruction  35 
fields,  disassembly  34-35 
.FILE  pseudo-op  260 
files  205-6 

disk  202 

tape  202 
"Filling  the  Screen  with  the  Letter  A" 

program  68-69 
FOR-NEXT  LOOP,  ML  equivalent  of 

64,  162-65 
40-column  mode  4 
forward  branching  103-5 
GET  BASIC  command,  ML  equivalent 

of  165 
GET  BASIC  routine,  using  in  ML 

132-35 
GET  ROM  routine  207 
G  (Go)  monitor  instruction  36 
GO  64  ROM  routine  208 
GOSUB  BASIC  command,  ML  equiva- 
lent of  165-66 
GOTO  BASIC  command,  ML  equiva- 
lent of  166-68 
hexadecimal  notation 

advantages  of  11-12 

how  to  use  15-16 

390 


hex  dump  24,  38 
"Hex  Practice"  program  21-22 
H  (Hunt)  monitor  instruction  36-37 
IF-THEN  BASIC  command,  ML  equiva- 
lent of  168 
immediate  addressing  35,  43-44,  60-61 
implied  addressing  61-63 
INC  instruction  69,  106,  229 
increment  and  decrement  double-byte 

numbers  subroutine  343-44 
indirect  X  addressing  71-72 
indirect  Y  addressing  69-71 
INPUT  BASIC  command,  ML  equiva- 
lent of  169-70 
INPUT  ROM  routine  204 
INPUT#  ROM  routine  203 
instruction,  ML  x,  23 
instructions,  length  of  53-55 
instruction  set,  8502  91-126,  215-46 
interactive  programming  46-47 
interpreted  code  131 
INX  instruction  63,  79,  96,  106,  229 
INY  instruction  63,  69,  106,  230 
J  (Jump)  monitor  instruction  37 
JMP  instruction  23,  101,  113,  114, 

119-20,  194,  230 
JMP  long  ROM  routine  193  210 
JSR  instruction  63,  101,  105,  113,  114, 

129,  131,  231 
JSR  long  ROM  routine  193,  210 
jump  table  130-31 
Kernal  130,  140,  201 
Kernal  routine.  See  ROM  routine 
keyboard  matrix  code  76 
keypress,  checking  for  76,  196-97,  207 
labels,  LADS  and  254-57 
LADS  assembler  ix-x,  3-7,  25,  86 

chained  files  and  259-62 

commands  251-52 

how  to  use  247-66 

instructions  28 

labels  254-57 

loading  5 

longer  programs  and  259-62 

modifying  266 

object  code  364-78 

pseudo-ops  249-52 

rules  for  262-65 

source  code  275-342 

starting  address  and  248 

typing  in  349-59 

use  like  BASIC  247 
LDA  instruction  25,  61,  63,  35,  78,  79, 

80,  91,  93-97,  99,  101,  105,  191,  194, 

231-32 
LDA  long  ROM  routine  193,  196,  210 


u 
u 
u 
u 
u 


u 
u 
u 
u 
u 


n 


i   \ 


i   \ 


:     ) 


LDX  instruction  72,  232 

LDY  instruction  233 

LEFT$  BASIC  function,  ML  equivalent 
of  183 

LEN  BASIC  function,  ML  equivalent  of 
183-84 

LET  BASIC  command,  ML  equivalent 
of  170-72 

LIST  BASIC  command,  ML  equivalent 
of  172-73 

listing  conventions,  BASIC  349-50 

L  (Load)  monitor  instruction  37-38 

LOAD  BASIC  command,  ML  equiva- 
lent of  173 

loader,  BASIC  xi 

"Loader"  program  378 

LOAD  ROM  routine  205-6 

long  jumps  21-11 

long  ROM  routine  193,  194,  196,  210, 
211 

Loop  instruction  group  106-12 

LSR  instruction  72,  85,  97,  124,  233-34 

machine  language 
code,  locating  in  memory  4 
programs,  reading  22 
versus  BASIC  xii-xiv 

"Machine  Language  Editor,  MLX"  pro- 
gram 353-58,  360-64 

math,  LADS  and  257-58 

memory  map  59 

memory  map,  Commodore  128  267-74 

MID$  BASIC  function,  ML  equivalent 
of  184 

ML.  See  machine  language 

"MLX  Machine  Language  Editor"  pro- 
gram 353-58,  360-64 

M  (Memory)  monitor  instruction  38, 
193 

mnemonic  23 

monitor 
bugs  and  33 
memory  in  193-95 
modifying  code  with  33-34 
running  program  from  36 
using  41-43 

monitor  mode  16 

multibyte  addition  and  subtraction  sub- 
routine 346-47 

multiplication  84-85 

multiplication  subroutine  347-48 

natural  numbers  11-13 

NEW  BASIC  command,  ML  equivalent 
of  173-74 

N  flag  93,  95-96,  97 

NOP  instruction  34,  63,  122,  234 

object  code  22 


octal  notation  15 

offset  67, 105 

ON-GOSUB  BASIC  command,  ML 
equivalent  of  174-75 

ON-GOTO  BASIC  command,  ML 
equivalent  of  175 

opcode  23,  78 

OPEN  ROM  routine  202-3 

operation  code.  See  opcode 

.6  pseudo-op  261 

ORA  instruction  123,  234-35 

OUTPUT*  ROM  routine  203 

page  43 

parameter  117 

PC  (program  counter)  33,  53,  79,  93 

PHA  instruction  63,  96,  235 

PHP  instruction  63,  96,  236 

PLA  instruction  63,  96,  114,  236 

PLP  instruction  63,  96,  236-37 

portability  129 

PRINT  BASIC  command,  ML  equiva- 
lent of  176-79 

PRINT  BASIC  routine,  using  in  ML 
132-35 

PRINT  ROM  routine  204 

processor  status  flags.  See  SR 

program,  building  a  139-54 

programming  techniques  41,  46-49 

pseudo-op  250-52 

+  pseudo-op  257-58 

#>  pseudo-op  258-59 

#<  pseudo-op  258-59 

RAM,  reserving  for  ML  141-43 

READ  BASIC  command,  ML  equivalent 
of  179 

register  38-39,  53,  55,  79,  94-95 

relative  addressing  63-66 

REM  BASIC  command,  ML  equivalent 
of  1119-80 

restore  default  I/O  ROM  routine  203 

RETURN  BASIC  command,  ML  equiva- 
lent of  180 

RIGHTS  BASIC  function,  ML  equiva- 
lent of  184-85 

ROL  instruction  72,  124,  237-38 

ROM  routine  129,  146,  194,  201-11 

ROR  instruction  72,  91,  124,  238-39 

R  (Registers)  monitor  command  38-39 

RTI  instruction  91,  125,  239 

RTS  instruction  24,  36,  63,  113,  114, 
239 

RUN  BASIC  command,  ML  equivalent 
of  10-81 

safe  memory  locations  60,  139-40 

SAVE  BASIC  command,  ML  equivalent 
of  181 
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SAVE  ROM  routine  206 
SBC  instruction  87,  97,  240 
screen  3 
"Searcher"  program  139-54 

program  discussion  143-49 
SEC  instruction  61,  84,  87,  97,  240 
SED  instruction  61,  81,  91,  240-41 
SEI  instruction  125,  241-42 
set  bank  number  ROM  routine  202 
set  filename  ROM  routine  202 
set  2,8,1  ROM  routine  201-2 
sign  95 

68000  chip  142 
6502  chip  125-26  . 
6510  chip  125-26 
snow  96-97 
source  code  22,  28 
SP  (Stack  Pointer)  53 
speed  switch  197 
SR  54,  55,  56 

S  (Save)  monitor  instruction  39 
stack  43,  60,  96-97,  113-17 
stack  pointer  39 
STA  instruction  25,  69,  78,  91,  93,  95, 

96,  242 
STA  long  ROM  routine  196,  211 
starting  address  6,  248 
STOP  BASIC  command,  ML  equivalent 

of  181 
strings  108-13 

STX  instruction  72,  93,  95,  96,  243 
STY  instruction  93,  243 
subprogram  252 
subroutine  41-42,  113-19 


subroutine  and  jump  instruction  group 

113-20 
subroutine  library  343-48 
subtraction  84 
SYS  BASIC  command  24 
SYS  BASIC  command,  ML  equivalent 

of  182 
TAB  BASIC  function,  ML  equivalent  of 

185-86 
tables,  searching  82-83 
"Tables"  subprogram  252 
TAX  instruction  95,  243 
TAY  instruction  95,  244 
test  RUN/STOP  key  ROM  routine  206 
Transporter  instruction  group  93-97 
TSX  instruction  96,  244 
T  (Transfer)  monitor  instruction  39-40 
TXA  instruction  61,  63,  80,  95,  244 
TXS  instruction  96,  245 
TYA  instruction  53,  61,  95,  246 
unknown  forward  branches  66-67 

V  (Verify)  monitor  instruction  40 

V  flag  97 

X  (exit  to  BASIC)  monitor  instruction 

40 
X  register  55-56 

V  register  55-56 
Z80  chip  142 
zero  page  140 

zero  page,  X  addressing  67 

zero  page,  Y  addressing  72 

zero  page  addressing  43-44,  58-60,  79 

Z  flag  93,  96,  97 


u 
u 
u 

\  > 


\    ) 


u 
Li 


392 


u 


/     I 


n 


n 


i 


\ 


To  order  your  copy  of  128  LADS  Disk,  call  our  toll-free  US 
order  line:  1-800-346-6767  (in  NY  212-887-8525)  or  send  your 
prepaid  order  to: 

128  LADS  Disk 
COMPUTE!  Publications 
P.O.  Box  5038 
F.D.R.  Station 
New  York,  NY  10150 

All  orders  must  be  prepaid  (check,  charge,  or  money  order).  NC 
residents  add  4.5%  sales  tax. 

Send  copies  of  128  LADS  Disk  at  $12.95  per  copy. 

(033BDSK) 

Subtotal  $ 

Shipping  and  Handling:  $2.00/disk  $ 

Sales  tax  (if  applicable)  $ 

Total  payment  enclosed  $ 


a  Payment  enclosed 

d  Charge  a  Visa  d  MasterCard  a  American  Express 

Acct.  No.  Exp.  Date 


(Required) 


Name 


Address 


PI  City  State  Zip 

Please  allow  4-5  weeks  for  delivery. 

H 


46203323 
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COMPUTE!  Books 


i  i 


Ask  your  retailer  for  these  COMPUTE!  Books  or  order 
directly  from  COMPUTE!. 

Call  toll  free  (in  US)  800-346-6767  (in  NY  212-887- 
^  8525)  or  write  COMPUTE!  Books,  P.O.  Box  5038,  F.D.R. 

PI  Station,  New  York,  NY  1 01 50. 

Quantity    Title  Price'         Total 

SpeedScript:  The  Word  Processor  for  the 

J""""!                            Commodore  64  and  VIC-20  (94-9)  $  9.95  

'      '              Commodore  SpeedScript  Book  Disk  $12.95  

128  Machine  Language  for  Beginners  (033-5)  $16.95  

r— t               COMPUTEI's  Commodore  64/128  Collection  (97-3)  $12.95  

I     t              All  About  the  Commodore  64.  Volume  Two  (45-0)  $16.95  

All  About  the  Commodore  64.  Volume  One  (40-X)  $12.95  

Programming  the  Commodore  64: 

The  Definitive  Guide  (50-7)  $24.95  

COMPUTEI's  Data  File  Handler  for  the 

Commodore  64  (86-8)  $12.95  

COMPUTEI's  Kids  and  the  Commodore  128(032)  $14.95  

Kids  and  the  Commodore  64  (77-9)  $12.95  

COMPUTEI's  Commodore  Collection,  Volume  1  (55-8)  $12.95  

COMPUTEI's  Commodore  Collection,  Volume  2  (70-1)  $12.95  

COMPUTEI's  Personal  Accounting  Manager  for  the 

Commodore  64  (014-9)  $12.95  

COMPUTEI's  VIC-20  and  Commodore  64 

Tool  Kit:  BASIC  (32-9)  $16.95  

COMPUTEI's  VIC-20  and  Commodore  64 

Tool  Kit:  Kernal  (33-7)  $16.95  

COMPUTEI's  Telecomputing  on  the 

Commodore  64  (009)  $12.95  

COMPUTEI's  VIC-20  Collection  (007)  $12.95  

Programming  the  VIC  (52-3)  $24.95  

VIC  Games  for  Kids  (35-3)  $12.95  

COMPUTEI's  First  Book  of  VIC  (07-8)  $12.95  

COMPUTEI's  Second  Book  of  VIC  (16-7)  $12.95  

COMPUTEI's  Third  Book  of  VIC  (43-4)  $12.95  

Mapping  the  VIC  (24-8)  $14.95  

COMPUTEI's  VIC-20  Collection  (007)  $12.95  
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•Add  $2.00  per  book  for  shipping  and  handling. 
Outside  US  add  $5.00  air  mall  or  $2.00  surface  mail. 

NC  residents  add  4.5%  sales  tax  

Shipping  &  handling:  $2.00/book  

Total  payment  


All  orders  must  be  prepaid  (check,  charge,  or  money  order). 

All  payments  must  be  in  US  funds. 

□  Payment  enclosed. 

Charge    □  Visa    □  MasterCard    □  American  Express 

Acct.  No Exp.  Date- 
Name 


(Required) 


Address- 


City State Zip_ 

•Allow  4-5  weeks  for  delivery. 

Prices  and  availability  subject  to  change. 

Current  catalog  available  upon  request. 


46203313 
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, ,  If  you've  enjoyed  the  articles  in  this  book,  you'll  find 

!    i         the  same  style  and  quality  in  every  monthly  issue  of 
COMPUTEE's  Gazette  for  Commodore. 
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For  Fastest  Service 
Call  Our  Toil-Free  US  Order  Line 

1-800-247-5470 

In  Iowa  call  1-800-532-1272 


COMPUTED  Gazette 

P.O.  Box  10957 

Des  Moines,  IA  50340 

My  computer  is: 

□  Commodore  64    □  VIC-20    □  Other. 


□  $24  One  Year  US  Subscription 
D  $45  Two  Year  US  Subscription 

□  $66  Three  Year  US  Subscription 

Subscription  rates  outside  the  US: 

□  $30  Canada 

□  $65  Air  Mail  Delivery 

□  $30  International  Surface  Mail 

Name 


Address 


City State Zip. 

Country 

r— t  Payment  must  be  in  US  funds  drawn  on  a  US  bank,  international 

i    I  money  order,  or  charge  card.  Your  subscription  will  begin  with  the 

next  available  issue.  Please  allow  4-6  weeks  for  delivery  of  first  issue. 

Subscription  prices  subject  to  change  at  any  time. 

I 1  □  Payment  Enclosed    □  Visa 

□  MasterCard  □  American  Express 


r_l  Acct,  No. Expires [_ 

H 


(Required) 


n 


The  COMPUTERS  Gazette  subscriber  list  is  made  available  to  carefully  screened 
organizations  with  a  product  or  service  which  may  be  of  interest  to  our  readers.  If  you 
prefer  not  to  receive  such  mailings,  please  check  this  box  a 

46222033 


I ) 

LJ 
U 
U 


u 
u 
u 

u 


n 


If  you've  enjoyed  the  articles  in  this  book,  you'll  find  the 
same  style  and  quality  in  every  monthly  issue  of  COM- 
PUTE! Magazine.  Use  this  form  to  order  your  subscription 
to  COMPUTE!. 

For  Fastest  Service 
Call  Our  Toil-Free  US  Order  Line 

1-800-247-5470 

In  IA  call  1-800-532-1272 


COMPUTE! 

P.O.  Box  10954 

Des  Moines,  IA  50340 

My  computer  is: 

□  Commodore  64  or  128  □  TI-99/4A  □  IBM  PC  or  PCjr  □  VIC-20 

□  Apple  □  Atari  □  Amiga  □  Other 

D  Don't  yet  have  one... 


□  $24  One  Year  US  Subscription 

□  $45  Two  Year  US  Subscription 

□  $65  Three  Year  US  Subscription 

Subscription  rates  outside  the  US: 

□  $30  Canada  and  Foreign  Surface  Mail 

□  $65  Foreign  Air  Delivery 

Name 


Address 


City State Zip 

Country 

Payment  must  be  in  US  funds  drawn  on  a  US  bank,  international 
money  order,  or  charge  card. 
I    J  □  Payment  Enclosed    □  Visa 

□  MasterCard  □  American  Express 

(1  Acct.  No. Expires / 

(Required) 

H 

Your  subscription  will  begin  with  the  next  available  issue.  Please 
allow  4-6  weeks  for  delivery  of  first  issue.  Subscription  prices  subject 
j    I-  to  change  at  any  time. 

'    .   r  462)9333 
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By  the  author  of  the  bestselling  Machine  Language  for  Beginners, 
about  which  the  critics  have  said: 

"Understandable"— The  New  York  Times 

"If  you  know  BASIC  and  want  to  learn  machine  language, 
this  is  the  place  to  start... Building  on  your  experience  as  a  BASIC 
programmer,  Mansfield  very  gently  takes  you  through  the  fun- 
damentals of  machine  language."— Whole  Earth  Software  Catalog 

"The  great  majority  of  books  about  machine  language  assume 
a  considerable  familiarity  with  both  the  details  of  microprocessor 
chips  and  with  programming  technique.  This  book  assumes  only  a 
working  knowledge  of  BASIC.  It  was  designed  to  speak  directly  to 
the  amateur  programmer,  the  part-time  computerist.  It  should  help 
you  make  the  transition  from  BASIC  to  machine  language  with  rel- 
ative ease."— From  the  Preface 

Contains  everything  you  need  to  learn  8502  machine  language 
including: 

•  A  dictionary  of  all  major  BASIC  words  and  their  machine  language 
equivalents.  This  section  contains  many  sample  programs  and 
illustrations  of  how  all  the  familiar  BASIC  programming  techniques 
are  accomplished  in  machine  language. 

•  The  LADS  assembler.  A  full-featured,  commercial-quality,  label- 
based  programming  language  which  supports  18  pseudo-ops,  la- 
bels, multiple  statements  on  a  line,  named  variables,  and  remarks. 

Automatically  switches  between  disk-based  mode  for  large 
linked  files  or  ultra-fast  memory-based  assembly  mode.  Automatic 
output  to  memory,  screen,  disk  (1541  or  1571),  or  printer.  (Cas- 
sette users  must  save  the  results  via  the  built-in  monitor.)  Uses 
full  128  RAM,  2  MHz  fast  assembly,  40-  or  80-column  screen 
modes. 

•  Easy-to-understand  descriptions  of  how  you  can  make  the  best 
use  of  all  the  new  features  available  on  the  128. 

•  All  8502  commands  fully  explained  and  arranged  for  easy 
reference. 

•  Special  chapters  on  the  128  programming  environment  and  the 
expanded  Kernal. 

•  Many  clear,  understandable  examples  and  comparisons  to  already 
familiar  BASIC  programming  methods. 

•  A  library  of  frequently  used  subroutines. 

For  1541  or  1571  disk,  cassette,  40-  or  80-column  mode. 
ISBN  0-87455-033-5 

Most  of  the  programs  in  this  book  are  available  on  a  companion  disk.  See  the  coupon  in  the 
back  for  details. 
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